jsdoc - 长 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
 */

但是由于大多数公司(出于合法的可读性原因)都有行长度限制，因此上述内容通常是 Not Acceptable 。但是，我无法弄清楚打破这些线条的“正确”方式应该是什么。

我可以做:

/**
 * @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 中有两种处理换行符的正确方法。第一个显然是 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 风格指南: https://google.github.io/styleguide/jsguide.html#jsdoc-line-wrapping

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

我建议使用缩进方法 - 我认为这是注释上下文的清晰度和可读性之间的一个很好的交叉(没有极短的行)