5

現在、JSDoc を使用して API の 1 つを文書化しています。これはうまく機能しますが、私が本当に困っていることの 1 つは、重複したドキュメントが発生することです。この一般的な例の 1 つは、プロパティとそのゲッターのドキュメントです。

function AClass() {
    /**
     * The current state of the object. Determines wether this object has been initialized yet.
     * @type {String}
     * @private
     */
    this._state = "initalized";
}

/**
 * Returns the current state of the object, which determines if the object has been initalized yet.
 * @return {String} The current state of the object
 */
AnObject.prototype.getState = function() {
    return this._state;
}

誰もがここで問題を見ていると思います。プロパティは、実際には 3 回ドキュメント化されています (プライベート プロパティ自体、getter メソッドの説明、およびメソッドの戻り値)。メソッドの説明を次のように単純に変更することReturns the stateは、実際にはオプションではありません。私は通常、ドキュメント出力でプライベート プロパティを非表示にしているためです。

そのような場合のベストプラクティスがあるかどうか、および他の人がこれをどのように処理しているかに興味があります。DRY に取りつかれている人として、これらのケースを処理するためのより良いオプションがあるべきだと思われます。

4

1 に答える 1

2

私もそれに気づき、少し面倒なことに同意しますが、同時に完璧な解決策があるとは思いません.

おそらくできることは次のようなものです

/**
 * Getter for {@link AClass._state}
 * @return {String} Returns {@link AClass._state}
 */
于 2015-04-01T19:30:34.180 に答える