web-dev-qa-db-fra.com

Comment documenter les classes ECMA6 avec JSDoc?

Contexte

J'ai un projet dans Nodejs utilisant des classes ECMA6 et j'utilise JSDoc pour commenter mon code, afin de le rendre plus accessible aux autres développeurs.

Cependant, mes commentaires ne sont pas bien acceptés par l'outil, et ma documentation est une épave de train.

Problème

Mon problème est que je ne sais pas comment documenter les classes ECMA6 avec JSDoc et je ne trouve aucune information décente.

Ce que j'ai essayé

J'ai essayé de lire l'exemple officiel mais je le trouve manquant et incomplet. Mes classes ont des membres, des variables constantes et bien plus encore, et je ne sais généralement pas quelles balises utiliser pour quoi.

J'ai également effectué une recherche approfondie sur le Web, mais la plupart des informations que j'ai trouvées sont antérieures à 2015, où JSDocs ne supportait pas encore les scripts ECMA6. Les articles récents sont rares et ne couvrent pas mes besoins.

La chose la plus proche que j'ai trouvée était ce problème GitHub:

Mais il est désormais dépassé.

Objectif

Mon objectif principal est d'apprendre à documenter les classes ECMA6 dans NodeJS avec JSDoc.

J'ai un exemple précis que j'aimerais voir fonctionner correctement:

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

Compte tenu de cet exemple de mini-classe ci-dessus, comment procéder pour le documenter à l'aide de JSDoc?

Un exemple sera apprécié.

javascriptnode.jsdocumentationjsdoc
14
Flame_Phoenix

Réponse tardive, mais depuis que je suis tombé sur quelque chose d'autre sur Google, j'ai pensé que j'aurais une fissure.

Vous avez probablement déjà découvert que le site JSDoc a des explications et des exemples décents sur la façon de documenter les fonctionnalités d'ES6.

Cela dit, voici comment je documenterais votre exemple:

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

Notez que @const implique en lecture seule et automatiquement par défaut. JSDoc récupérera correctement l'exportation, la @class et la @constructor, donc seules les bizarreries comme les membres privés doivent être spécifiées.

19
Fred Stark

Pour toute personne visitant cette question en 2019:
La réponse donnée par @FredStark est toujours correcte, cependant, les points suivants doivent être notés:

  1. La plupart/tous les liens de cette page sont morts. Pour la documentation du JSDoc, vous pouvez voir ici .
  2. Dans de nombreux IDE ou éditeurs de code (tels que VSCode), vous trouverez des compléments automatiques tels que @class ou @constructor qui ne sont pas nécessaires pour le cas des classes ES6 car ces éditeurs reconnaîtront le constructeur après le mot clé new.
2
Ramtin