Page MenuHomePhabricator

Standardize use of @description and @classdesc
Closed, ResolvedPublic

Description

Rationale for changes in 1021584 and 1021601

These patches:

  • Use @classdesc for class descriptions and @description for constructor descriptions for all classes
  • Move constructor descriptions that are not specific to the constructor to the class description
  • Remove constructor descriptions that are redundant with class descriptions
  • Move constructor descriptions under the @constructor tag to make it more clear what they are used for and to replicate the order that they appear on the site (class description first, then constructor description)

JSDuck does not display constructor descriptions at all. Instead, main doc-block descriptions are added to the beginning of the class description sections. For example, on mw.Api, "Client library for the action API. See mw.Rest for the REST API. See also https://www.mediawiki.org/wiki/API:Main_page." is the constructor description, everything else is the class description. There is no description displayed in the constructor section.

As a result of this JSDuck behavior, class and constructor descriptions are used inconsistently in MediaWiki core:

  • Prior to migration, most classes didn't have have a @classdesc. During migration, we added some class descriptions, but we didn't have this standard figured out yet, so it's inconsistent.
  • Constructor descriptions often just document the class as a whole, not the constructor specifically.
  • Many classes do not have true constructor description.

Why move the constructor descriptions out of the main doc block description?

  • It's unclear what the constructor description is used for when looking at the comment.
  • In the comment, the constructor description appears before the class description, so it's easy to mistake it for something that should include a general description of the class. This happened with some of our migration patches: we were misled by the order of the descriptions and put a general statement about the class in the constructor description.

For example, for mw.Api, the existing constructor description ("Client library for the action API. See mw.Rest for the REST API. See also https://www.mediawiki.org/wiki/API:Main_page.") documents the class as a whole, not the constructor. This link to the wiki page is important enough that it should go in the main section of the page. To fix this, I moved this information to the main class description. Since there was no description specifically for the constructor, I left it without a constructor description.

Background
On class pages, the main description from the doc block documents the constructor while the @classdesc documents the class.(JSDoc has various fallback behaviors if there is no @classdesc.) While this is the intended behavior of these fields in JSDoc, this separation is a bit counterintuitive for doc writers since they need to imagine the information appearing in reverse order from the way it appears in the doc block.

Currently in MediaWiki Core, the main doc block description is mostly used to document the class, and @classdesc is used inconsistently (12 instances). We could modify the theme so that both these fields appear as the class description, but that would remove the ability to add a description to the constructor, which is sometimes needed (see mw.Message and mw.Title).

Proposal

Example: mw.Map

Code (current):

/**
 * ES3 compatible class similar to [ES6 Map]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map}.
 *
 * @class mw.Map
 * @classdesc Create an object that can be read from or written to via methods that allow
 * interaction both with single and multiple properties at once.
 * @example
 *
 *   const map = new mw.Map();
 *   map.set( 'foo', 5 );
 *   alert( 5 === map.get( 'foo' ) );
 */

Code (proposed):

/**
 * @classdesc ES3 compatible class similar to [ES6 Map]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map}.
 * @class mw.Map
 * @description Create an object that can be read from or written to via methods that allow
 * interaction both with single and multiple properties at once.
 * @example
 *
 *   const map = new mw.Map();
 *   map.set( 'foo', 5 );
 *   alert( 5 === map.get( 'foo' ) );
 */
JSDoc (current)JSDoc (proposed)
Screenshot 2024-02-09 at 10.07.21 AM.png (510×640 px, 50 KB)
Screenshot 2024-02-16 at 11.50.10 AM.png (521×664 px, 51 KB)

Rationale

  • Make it easy for doc writers to conceptualize the information by reflecting the same order on the JSDoc site as in the doc block.
  • Provide a recommended way to use these fields going forward.

Event Timeline

apaskulin triaged this task as Medium priority.Feb 9 2024, 6:16 PM
apaskulin moved this task from Backlog to To be discussed further on the JSDoc WMF theme board.
apaskulin renamed this task from Move class description under title to Move main class description under title.Feb 9 2024, 6:19 PM

I think this is generally worthwhile, because the current state of things is confusing. It looks like the main body of the doc comment is interpreted as the documentation for the constructor, and only the @classdesc is interpreted as the documentation for the class. In most cases I think the text in the main body of the doc comment is intended to be about the class, not the constructor.

However, it would be nice if we could retain the ability to document the constructor separately in some way, because sometimes we do want to do that if there's some sort of peculiarity (see for example mw.Message and mw.Title, where calling the constructor is either discouraged or not possible).

However, it would be nice if we could retain the ability to document the constructor separately in some way, because sometimes we do want to do that if there's some sort of peculiarity (see for example mw.Message and mw.Title, where calling the constructor is either discouraged or not possible).

This is a good point. I'm not sure there's a way to do this short of creating a custom plugin. A more verbose option could be to omit the main body of the doc comment and instead document the class in the @classdesc and the constructor in a @description tag. This would preserve the correct information order but would require a lot of manual cleanup.

In researching this more, I found that the current behavior (@classdesc documents the class, main doc block documents the constructor) is the intended behavior of JSDoc (see the classdesc docs). In the interest of not going against the intended implementation, maybe it would be simpler in the long run to just use that behavior and do the initial manual cleanup needed to conform to it.

apaskulin renamed this task from Move main class description under title to Standardize use of @description and @classdesc.Feb 16 2024, 7:52 PM
apaskulin updated the task description. (Show Details)

A more verbose option could be to omit the main body of the doc comment and instead document the class in the @classdesc and the constructor in a @description tag.

We decided to move forward with this option in the JSDoc sync meeting. I've updated the task to capture this.

Change 1007695 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[jsdoc/wmf-theme@master] templates: Display examples in class description

https://gerrit.wikimedia.org/r/1007695

Change 1007695 merged by jenkins-bot:

[jsdoc/wmf-theme@master] templates: Display examples in class description

https://gerrit.wikimedia.org/r/1007695

Change 1007944 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[jsdoc/wmf-theme@master] templates: Display class description summary in class lists

https://gerrit.wikimedia.org/r/1007944

Change #1013396 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[jsdoc/wmf-theme@master] templates: Consistent page organization

https://gerrit.wikimedia.org/r/1013396

Change #1014617 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[jsdoc/wmf-theme@master] plugins: Fork summarize plugin from JSDoc

https://gerrit.wikimedia.org/r/1014617

Change #1013396 merged by jenkins-bot:

[jsdoc/wmf-theme@master] templates: Consistent page organization

https://gerrit.wikimedia.org/r/1013396

Change #1014617 merged by jenkins-bot:

[jsdoc/wmf-theme@master] plugins: Fork summarize plugin from JSDoc

https://gerrit.wikimedia.org/r/1014617

Change #1007944 abandoned by Alex Paskulin:

[jsdoc/wmf-theme@master] templates: Display class description summary in class lists

Reason:

in favor of https://gerrit.wikimedia.org/r/c/jsdoc/wmf-theme/+/1014617

https://gerrit.wikimedia.org/r/1007944

apaskulin updated the task description. (Show Details)

Change #1019301 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[jsdoc/wmf-theme@master] templates: Remove source link from main page description

https://gerrit.wikimedia.org/r/1019301

Change #1019301 merged by jenkins-bot:

[jsdoc/wmf-theme@master] templates: Remove source link from main page description

https://gerrit.wikimedia.org/r/1019301

Change #1021584 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Standardize use of class descriptions in JSDoc

https://gerrit.wikimedia.org/r/1021584

Test wiki created on Patch demo by APaskulin (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/353e5d877e/w

Change #1021601 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[mediawiki/core@master] docs: Standardize use of class descriptions in JSDoc

https://gerrit.wikimedia.org/r/1021601

Test wiki created on Patch demo by APaskulin (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/6f08fc1b03/w

Change #1021584 merged by jenkins-bot:

[mediawiki/core@master] docs: Standardize use of class descriptions in JSDoc

https://gerrit.wikimedia.org/r/1021584

Change #1021601 merged by jenkins-bot:

[mediawiki/core@master] docs: Standardize use of class descriptions in JSDoc

https://gerrit.wikimedia.org/r/1021601

apaskulin updated the task description. (Show Details)