长JSDoc线的正确/规范格式是什么？

Question

所有官方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行（在代码中，而不是在生成的JSDoc中）的正确/官方/规范方式是什么...或者实际上是任何长注释行。

Answer 1

在JSDoc中有两种处理换行符的正确方法。第一个，显然是谷歌使用的，是在第一个之后缩进行：

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

第二个是基于JSDoc派生自JavaDoc的事实，这与您的第二个示例类似。有关JavaDoc示例，请参阅以下链接： http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide

我建议使用缩进方法 - 我认为这是可读性与非常短线之间的良好交叉。