Document behavior, gotchas, etc, for public TypeChecker API

[jakebailey]

A common (valid) complaint about our public API is that we don't have any documentation for what the methods do, why to use them, why not to use them, the gotchas, etc.

In more recent API PRs (like #52467 and #52473), we've added descriptions, but we should do the same for the existing methods if possible.

[jakebailey]

Related: typescript-eslint/typescript-eslint#6193 (comment)

[jakebailey]

This also came up during the ESLint/TS meeting a few weeks ago.

(cc @bradzacher @JoshuaKGoldberg @JamesHenry)

[DanielRosenwasser]

This is pretty vague - unless you have something in mind that you're already prepping a PR for. Otherwise, can we list 10 functions/methods that would be a good starting point?

[jakebailey]

I don't think I'm experienced enough to write the final versions; this is mainly so we don't forget about what we talked about in the meeting.

From the linked thread above, a start would be:

• getContextualType
• getApparentType
• "type" in general?

@bradzacher also mentioned instantiated types, but, I don't see that in our public API. I can't recall if there were specific requests otherwise.

[jakebailey]

Of course the best would be to require JSDoc comments on any and all TypeChecker APIs, but that seems like a lot for a first pass.

[uasan]

My feedback from the developer of the build system using the public API TS.

The lack of full-fledged API documentation has raised the threshold for entering the development of extensions for the compiler, as a result, there are few specialists and they have very good salaries, thank you for this, without irony.

The only relevant documentation is typescript.d.ts, but it's very difficult to find changes in new versions, it would be very helpful if we had a Changelog public API in What's New (https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html), which would list links to PRs that changed or added something to the public API, just links to the PR is very useful and relevant.