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
- Update the docs to recommend that classes are documented using @classdesc and constructors are documented using @description
- Manually fix doc blocks in Core to conform to this
- Update the theme to display examples in the class description instead of under the constructor https://gerrit.wikimedia.org/r/c/jsdoc/wmf-theme/+/1007695
- Fix so that example still appear if there is no class description https://gerrit.wikimedia.org/r/c/jsdoc/wmf-theme/+/1013396
- T359120: Move class list above constructor
- Update the theme to use the @classdesc instead of the @description in class lists, such as https://doc.wikimedia.org/mediawiki-core/master/js/mw.html https://gerrit.wikimedia.org/r/c/jsdoc/wmf-theme/+/1014617
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) |
|---|---|
 |  |
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.