Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove GLOBALS in api docs #4343

Merged
merged 4 commits into from
Jul 2, 2020
Merged

Conversation

craigtaub
Copy link
Contributor

We should not document any globals in the context of programmatic usage, which is the target for the api docs.
The Members and Methods we have listed live are currently mostly wrong and sometimes sending people down the wrong path. By removing them we remove confusion.

I have given an explicit module directive name to fix the Methods, the other half of Members were manual tags.

Alternative design

We could remove the module directive from the "interfaces/common" module, which leaves just the hooks (after/afterEach/before/beforeEach).
But I decided it was better to have either ALL of the available globals given, or none of them.

Screens

On live

Screenshot 2020-06-07 at 16 33 15

On local - section gone

Screenshot 2020-06-23 at 15 02 14

Applicable issues

#4317

@craigtaub craigtaub added area: documentation anything involving docs or mochajs.org semver-patch implementation requires increase of "patch" version number; "bug fixes" labels Jun 23, 2020
@craigtaub craigtaub force-pushed the craigtaub/4317-fix-api-docs-globals branch from fd8c0e7 to e9e0292 Compare June 23, 2020 14:12
@coveralls
Copy link

coveralls commented Jun 23, 2020

Coverage Status

Coverage remained the same at 93.766% when pulling 0c49a54 on craigtaub/4317-fix-api-docs-globals into a1d3984 on master.

Copy link
Contributor

@boneskull boneskull left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks fine to me. If I had my way, I'd rename all of the @module tags to be equivalent to their filepaths from lib, e.g., @module common becomes @module interfaces/common. I think that's allowed in jsdoc.

I note that lib/browser/progress.js should be moved to lib/browser/reporters/progress.js at some point.

@craigtaub craigtaub merged commit 7d3151d into master Jul 2, 2020
@craigtaub craigtaub deleted the craigtaub/4317-fix-api-docs-globals branch July 2, 2020 11:19
@craigtaub craigtaub added this to the next milestone Jul 2, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area: documentation anything involving docs or mochajs.org semver-patch implementation requires increase of "patch" version number; "bug fixes"
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants