How to document ECMA6 classes with JSDoc?
Solution 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.
Solution 2
For anyone visiting this question in 2019:
The answer given by @FredStark is still correct, however, the following points should be noted:
- Most/all of the links in this page are dead. For the documentation of the JSDoc, you can see here.
- In many IDEs or code editors (such as VSCode), you will find auto-completions such as
@class
or@constructor
which are not necessary for the case of ES6 classes since these editors will recognize the constructor after thenew
keyword.
![Flame_Phoenix](https://i.stack.imgur.com/KquuZ.jpg?s=256&g=1)
Flame_Phoenix
I have been programming all my life since I was a little boy. It all started with Warcraft 3 and the JASS and vJASS languages that oriented me into the path of the programmer. After having that experience I decided that was what I wanted to do for a living, so I entered University (FCT UNL ftw!) where my skills grew immensely and today, after several years of studying, professional experience and a master's degree, I have meddled with pretty much every language you can think of: from NASM to Java, passing by C# Ruby, Python, and so many others I don't even have enough space to mention them all! But don't let that make you think I am a pro. If there is one thing I learned, is that there is always the new guy can teach me. What will you teach me?
Updated on August 01, 2020Comments
-
Flame_Phoenix almost 4 years
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:
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.