Как документировать классы ECMA6 с помощью JSDoc?

Фон

У меня есть проект в Nodejs, использующий классы ECMA6, и я использую JSDoc для комментария моего кода, чтобы сделать его более доступным для других разработчиков.

Однако мои комментарии не очень хорошо принимаются инструментом, и моя документация-это крушение поезда.

Задача

Моя проблема заключается в том, что я не знаю, как документировать классы ECMA6 с помощью JSDoc, и я не могу найти никакой приличной информации.

Что я пробовал

Я попробовал читать официальный пример , но я нахожу его недостаточным и неполным. В моих классах есть члены, постоянные переменные и многое другое, и я обычно не знаю, какие теги для чего использовать.

Я также сделал обширный поиск в интернете, но большая часть информации, которую я нашел, относится к 2015 году, когда JSDocs еще не поддерживал скрипты ECMA6. Последние статьи редки и не покрывают моих потребностей.

Самое близкое, что я нашел, был этот GitHub Выпуск:

Но к настоящему времени она устарела.

Цель

Моя главная цель-научиться документировать классы ECMA6 в NodeJS с помощью JSDoc.

У меня есть точный пример, который я хотел бы видеть правильно работающим: 

/**
 * @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;

Вопрос

Учитывая приведенный выше пример мини-класса, как вы собираетесь документировать его с помощью JSDoc?

Пример будет оценен по достоинству.

1 3
javascript node.js documentation jsdoc

1 ответ:

Поздний ответ, но так как я наткнулся на этот гугл что-то еще, я думал, что у меня будет трещина в этом.

Вы, вероятно, уже обнаружили, что сайт JSDoc имеет приличные объяснения и примеры того, как документировать функции ES6.

Учитывая это, вот как я бы задокументировал ваш пример: 

/**
 * 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;

Обратите внимание, что @const подразумевает только чтение и автоматически по умолчанию. JSDoc правильно подберет экспорт, класс и конструктор, поэтому только такие странности, как private члены должны быть указаны.

5