web-dev-qa-db-ja.com

JSDocでECMA6クラスを文書化する方法は？

バックグラウンド

ECMA6クラスを使用するNodejsのプロジェクトがあり、他の開発者がアクセスしやすいように、コードにコメントするために JSDoc を使用しています。

ただし、私のコメントはツールで十分に受け入れられず、私のドキュメントは列車事故です。

問題

私の問題は、JSDocを使用してECMA6クラスを文書化する方法がわからず、適切な情報が見つからないことです。

私が試したもの

私は 公式の例 を読んでみましたが、それは不十分で不完全です。私のクラスにはメンバー、定数変数などがあり、通常、どのタグを何に使用するかわかりません。

また、ウェブで広範囲にわたる検索を行いましたが、私が見つけたほとんどの情報は、JSDocsがECMA6スクリプトをまだサポートしていない2015年より前のものです。最近の記事は少なく、私のニーズをカバーしていません。

私が見つけた最も近いものは、このGitHubの問題でした。

しかし、それは今では時代遅れです。

目的

私の主な目的は、JSDocを使用してNodeJSでECMA6クラスを文書化する方法を学ぶことです。

適切に動作させたい具体的な例があります。

/**
 * @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を使用してそれを文書化するにはどうすればよいでしょうか？

一例をいただければ幸いです。

javascriptnode.jsdocumentationjsdoc
14
Flame_Phoenix

遅い答えですが、私はこのグーグルに出くわしたので、私はそれで亀裂があると思いました。

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はエクスポート、@ classおよび@constructorを正しく取得するため、プライベートメンバーのような奇妙なものだけを指定する必要があります。

19
Fred Stark

2019年にこの質問にアクセスする人向け：
@ FredStarkの回答は依然として正しいですが、次の点に注意してください。

  1. このページのほとんどまたはすべてのリンクは無効です。 JSDocのドキュメントについては、 here を参照してください。
  2. 多くのIDEまたはコードエディター（VSCodeなど）では、@classまたは@constructorなどのオートコンプリートが見つかります。これらのエディターはES6クラスの後にコンストラクターを認識するため、ES6クラスの場合は必要ありません。 newキーワード。
2
Ramtin