长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？showow =Comments#Comments

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

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