web-dev-qa-db-ja.com

長いJSDoc行の適切な/正規のフォーマットは何ですか?

公式のJSDocの例にはすべて、次のような単純なドキュメント文字列があります。

/**
 * @param {string} author - The author of the book.
 */

問題は、実際のドキュメントでは長いドキュメント文字列がしばしばあることです。

/**
 * @param {string} author - The author of the book, presumably some person who writes well
 */

しかし、ほとんどの企業には(正当な読みやすさの理由から)行の長さに制限があるため、上記は受け入れられないことがよくあります。しかし、私が理解できないのは、それらの線を分割する「正しい」方法がどうあるべきかということです。

私はそれをできた:

/**
 * @param {string} author - The author of the book, presumably some
 * person who writes well
 */

しかし、それは読みにくいです。代わりに私はできる:

/**
 * @param {string} author - The author of the book, presumably some
 *                          person who writes well
 */

見栄えは良くなりますが、特にパラメータに長い名前が付いている場合は、大量の行が生成される可能性があります。

/**
 * @param {string} personWhoIsTheAuthorOfTheBook - The author of the
 *                                                 book, presumably
 *                                                 some person who
 *                                                 writes well
 */

だから私の質問は、長い形式の適切な/公式/正規の方法は何ですか@param lines(生成されたJSDocではなくコード内)...または実際には長い注釈行。

44
machineghost

JSDocの改行を処理する適切な方法は2つあります。 1つ目は、明らかにGoogleで使用されているように、最初の後に行をインデントすることです。

/**
 * @param {string} author - The author of the book, presumably some
 *     person who writes well and does so for a living. This is
 *     especially important for obvious reasons.
 */

これは、Google Javascriptスタイルガイドからです: http://google.github.io/styleguide/javascriptguide.xml?showone=Comments#Comments

2番目は、JSDocがJavaDocから派生しているという事実に基づいています。これは、2番目の例と同様です。 JavaDocの例については、次のリンクを参照してください。 http://www.Oracle.com/technetwork/Java/javase/documentation/index-137868.html#styleguide

インデント方法を使用することをお勧めします-読みやすさと極端に短い行を持たないことの間の良いクロスだと思います。

48
smartbei