> What are Unix man-pages but comments about the APIs they describe?
Documentation. Obviously not the same thing as inline comments in the code. You can generate documentation using comments (i.e. jsdoc), but comments are the weakest form of guidance for other developers. Types don't replace documentation, but are part of the same goal: making code easier to consume.
> When type-declarations become more complicated than the code they are describing
Do you find this happening to you often? JavaScript is a very permissive language, and most JS devs learn to write code in a way that is difficult to type. That's a part of the learning curve of the language. Part of using TS well, is realizing that complicated types are a smell for complicated behavior, and modeling your data in a conceptually simple way.
It's not just about labeling everything string or number, but making it impossible to use the code the wrong way.
> But if a declaration is very complicated how can we be sure there's no errors in it?
Simple. You test them. Same as any other code. How do you test your comments?