I think it’s time we adopt a standard way to document our APIs in the documentation because so far we’ve done it without too much rigor and it’s a bit of a mess.
I’m inclined to TSDoc from Microsoft because it’s the standard of TypeScript and all our APIs are written in TypeScript. It also has the benefit of having built-in support for VSCode, so the APIs we do in TSDocs also appear when people code in VSCode. It also supports markdown, which is cool.
I have no idea how to move/copy from TSDoc to our docs. Maybe we can generate some API-only docs automatically in each PR and copy and paste the relevant parts when writing the real docs. Something like TypeDoc could help.
I’m certainly not an expert on this so any feedback or other ideas are more than welcomed.