Repository navigation
Document behavior, gotchas, etc, for public TypeChecker API #53239
Description
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.
Activity
jakebailey commentedon Mar 13, 2023
Related: typescript-eslint/typescript-eslint#6193 (comment)
jakebailey commentedon Mar 13, 2023
This also came up during the ESLint/TS meeting a few weeks ago.
(cc Brad Zacher (@bradzacher) Josh Ghoulberg 👻 (@JoshuaKGoldberg) James Henry (@JamesHenry))
DanielRosenwasser commentedon Mar 13, 2023
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 commentedon Mar 13, 2023
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:
getContextualTypegetApparentTypeBrad Zacher (@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 commentedon Mar 13, 2023
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 commentedon Mar 14, 2023
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 aChangelog public APIinWhat'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.