**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](https://codesearch.wmcloud.org/core/?q=%40classdesc)). 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**
- [x] Update the [docs](https://www.mediawiki.org/wiki/Manual:Coding_conventions/JavaScript#Documentation_comments) to recommend that classes are documented using `@classdesc` and constructors are documented using `@description`
- [ ] Manually fix doc blocks in Core to conform to this
- [x] 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
- [x] Fix so that example still appear if there is no class description https://gerrit.wikimedia.org/r/c/jsdoc/wmf-theme/+/1013396
- [x] {T359120}
- [x] 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) |
| --- | --- |
| {F41829949} | {F41933471} |
**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.