Is GLOBAL in the API documentation correct?

[craigtaub]

Are globally scoped variables in the api docs correct?

Im not a JSDOC expert, but I would expect any globally scoped method to be available in a suite or test, yet many are not e.g. https://mochajs.org/api/global.html#runWithSuite.

Is there a mistake here? Are a couple missing the @module directive?

[boneskull]

No. there are many issues with the API organization. likely missing @module yes. none of these are always global. in fact we should not document ANY globals in the context of programmatic usage, which is the target for these doca

[boneskull]

essentially this is all messed up because we never made it the API docs a priority, and aren’t really rigid about it in PRs. there’s probably some way to automate it but I’d rather go full-TS-types-in-docstrings and generate docs that way. these are incompatible with the jsdoc processor.

[craigtaub]

we never made it the API docs a priority, and aren’t really rigid about it in PRs

In general we are pretty good with fixes/small features etc, but yeah things slip with the larger scale changes.

in fact we should not document ANY globals in the context of programmatic usage, which is the target for these docs

Yep sounds sensible.

I’d rather go full-TS-types-in-docstrings and generate docs that way

Yeah I know there is a separate and wider issues for this.