On @api JSDoc tag

[aweebit]

The @api JSDoc tag has been used in the library code since the initial commit. However, I have not been able to find any documentation on it. The fact its values are properly highlighted in VS Code is due to microsoft/vscode@9ad4bcd, which includes no explanation on why the highlighting was added. My best guess is that it was added just to cover de facto usage like that in Commander (see microsoft/vscode#189812).

The well-documented alternatives to @api private (which is currently used throughout the library) are @private and @access private. Should we use one of them instead?

[aweebit]

Found the progenitor commit adding the highlighting later adopted by VS Code: 31d2a5f

My assumption was right. The commit description reads:

Not part of the official JSDoc spec, yet occasionally used in-the-wild.

[shadowspawn]

Happy to change to @private.

---

I had noticed @api was not official in past, but it was used so consistently right from the start I just left it! The atom link that you found that added the support was interesting history.

The main documentation used to be generated on the gh-pages branch from the JSDoc and published separately. It is probably the reason we have such good JSDoc coverage! That process wasn't being maintained, and we switched to the README for the docs. (#299 #988)

The utility used to extract the JSDoc from the code did explicitly support @api private: https://github.com/tj/dox

[aweebit]

I found other usage examples and opened jsdoc/jsdoc#2066. Excited to see where it leads, but not expecting quick reaction since there has not been much activity in the repo recently.

[aweebit]

I've just realized @package should be used instead of @private or @api private because classes use each others' "private" methods all over the library.

[shadowspawn]

@package is technically accurate, but I had never seen it and had to look it up to confirm the meaning. I think @private is much clearer for Commander users seeing the tag.

[aweebit]

@package is technically accurate, but I had never seen it and had to look it up to confirm the meaning.

Unfortunately, it is indeed quite uncommon (only 10k results in GitHub Search).

I think @private is much clearer for Commander users seeing the tag.

The problem is that if you check out shadowspawn/commander.js@caf721c and then replace all @api private occurrences by @private, you will see a bunch of TypeScript errors that were not show before because @api private is not valid JSDoc, and in particular not currently supported by the TypeScript flavor of JSDoc, but that could change in the future.

I don't think we should keep using @api private just so that we can avoid errors because actually, it is supposed to simply be a synonym for @private, even though it currently isn't in tools other than Dox.

[aweebit]

And by the way, the TypeScript team strongly advocates for having public declarations even for private class members.

But again quite unfortunately, TypeScript does not have an accessibility modifier that would be matched by the JSDoc @package tag (although an issue proposing such a modifier has been open since 2015: microsoft/TypeScript#5228).

So if we follow the guidelines and add typings for all package-private stuff, nothing will stop library users from accessing it, and they will even see it suggested by IntelliSense. It really frustrates me that TypeScript is such a mess :(

[shadowspawn]

The problem is if you ... replace all @api private occurrences by @private, you will see a bunch of TypeScript errors that were not show before because @api private is not valid JSDoc

Oh, yes indeed. And to be fair, correct! I have been accessing some methods as "package" accessible rather than being strict. That raises the bar. Not sure whether I want to change anything.

[aweebit]

Just found out TypeScript recognizes @internal as a way to omit stuff from being included in declaration files under the stripInternal option. Could be exactly what we need.

[shadowspawn]

I prefer sticking with JSDoc for the Javascript tags, so could use mixture of @package // internal use only and @private. (Disclaimer: I have not experimented with this yet.)

[shadowspawn]

Released in Commander v12.0.0.