How to document ECMA6 classes with JSDoc?

Question

Background

I have a project in Nodejs using ECMA6 classes and I am using JSDoc to comment my code, as to make it more accessible to other developers.

However, my comments are not well accepted by the tool, and my documentation is a train wreck.

Problem

My problem is that I don't know how to document ECMA6 classes with JSDoc and I can't find any decent information.

What I tried

I tried reading the official example but I find it lacking and incomplete. My classes have members, constant variables and much more, and I don't usually know which tags to use for what.

I also made an extensive search in the web, but most information I found is prior to 2015 where JSDocs didn't support ECMA6 scripts yet. Recent articles are scarce and don't cover my needs.

The closest thing I found was this GitHub Issue:

• https://github.com/jsdoc3/jsdoc/issues/819

But it is outdated by now.

Objective

My main objective is to learn how to document ECMA6 classes in NodeJS with JSDoc.

I have a precise example that I would like to see work properly:

/**  * @fileOverview What is this file for?  * @author Who am I?  * @version 2.0.0  */  "use strict";  //random requirements.  //I believe you don't have to document these. let cheerio = require('cheerio');  //constants to be documented.  //I usually use the @const, @readonly and @default tags for them const CONST_1 = "1"; const CONST_2 = 2;  //An example class class MyClass {      //the class constructor     constructor(config) {         //class members. Should be private.          this.member1 = config;         this.member2 = "bananas";     }      //A normal method, public     methodOne() {        console.log( methodThree("I like bananas"));     }      //Another method. Receives a Fruit object parameter, public     methodTwo(fruit) {         return "he likes " + fruit.name;     }      //private method     methodThree(str) {        return "I think " + str;     } } module.exports = MyClass; 

Question

Given this mini class example above, how would you go about documenting it using JSDoc?

An example will be appreciated.

Answer 1

Late answer, but since I came across this googling something else I thought I'd have a crack at it.

You've probably found by now that the JSDoc site has decent explanations and examples on how to document ES6 features.

Given that, here's how I would document your example:

/**  * module description  * @module MyClass  */  //constants to be documented.   //I usually use the @const, @readonly and @default tags for them /** @const {String} [description] */ const CONST_1 = "1"; /** @const {Number} [description] */ const CONST_2 = 2;  //An example class /** MyClass description */ class MyClass {      //the class constructor     /**      * constructor description      * @param  {[type]} config [description]      */     constructor(config) {         //class members. Should be private.          /** @private */         this.member1 = config;         /** @private */         this.member2 = "bananas";     }      //A normal method, public     /** methodOne description */     methodOne() {        console.log( methodThree("I like bananas"));     }      //Another method. Receives a Fruit object parameter, public     /**      * methodTwo description      * @param  {Object} fruit      [description]      * @param  {String} fruit.name [description]      * @return {String}            [description]      */     methodTwo(fruit) {         return "he likes " + fruit.name;     }      //private method     /**         * methodThree description      * @private      * @param  {String} str [description]      * @return {String}     [description]      */     methodThree(str) {        return "I think " + str;     } } module.exports = MyClass; 

Note that @const implies readonly and default automatically. JSDoc will pick up the export, the @class and the @constructor correctly, so only the oddities like private members need to be specified.