Topic on Manual talk:Coding conventions/JavaScript

Chose option 2 and updated the page

Hi all, I'd like to discuss documentation comment conventions for classes as part of the migration to JSDoc. In JSDoc, specifically for classes:

• The main description in the documentation comment (or the @description tag) is interpreted as the description of the constructor
• The @classdesc tag is interpreted as the description of the class

These two description fields appear in the documentation site as:

# mw.MyClass
Class description

## Constructor
### new mw.MyClass()
Constructor description

There are two ways this can be formatted in the comment:

1. Constructor description first: Simpler but in reverse order from how the information appears on the documentation site

/**
 * Constructor description first line.
 * 
 * Constructor description continued...
 * 
 * @classdesc Class description first line.
 * 
 * Class description continued...
 * 
 * @param string myParam
 */

2. Class description first: More verbose but reflects the same order as the documentation site

/**
 * @classdesc Class description first line.
 * 
 * Class description continued...
 * 
 * @description Constructor description first line.
 * 
 * Constructor description continued...
 * 
 * @param string myParam
 */

The empty lines aren't required by JSDoc, but I've included them for readability and consistency with Manual:Coding conventions/Documentation.

Which option should we standardize on? Ideally, we'd be able to use @constructor instead of @description, but JSDoc doesn't support that. Of the two options, I think option 2 is the least ambiguous and easiest to reason about.

I think developers have a tendency to, whatever comes first in that block, is where we put high-level explainers, detailed descriptions, and usage examples for the class as a whole.

Having that be tucked away in the constructor description would be unfortunate and make the information less discoverable and thus waste investments in it somewhat.

For that reason, and for parity with PHP conventions wherever possible, I'd suggest option 2.

@APaskulin (WMF) I believe your code example is for the lower-level ("ES5-style") class, where the class and constructor are defined together as function FooBar(…) {…}.

When ES6 syntax sugar is used (which makes it look like the class and constructor are separate things), there is usually two separate doc blocks:

class FooBar {
 constructor() {…}
}

Can you add an example for this as well? Does it require the same tags? I'm hoping @description would no longer be needed in that case, and would @class stay in the first block?

That's a great point. This is much cleaner and works correctly:

/**
 * Class description.
 */
class myClass {
	/**
	 * Constructor description.
	 * 
	 * @param ...
	 */
	constructor() {...}
};

Adding a @class tag to the ES6 example (in either comment) actually messes it up and causes JSDoc to duplicate the class.

In the ES5 example, the @class tag isn't necessary in most cases, but it doesn't break anything. I included it because we have a lot of @class tags in MediaWiki core, but I'll update that post to remove it since it's not required.