JSDoc 长行的 proper/canonical 格式是什么？

Question

所有官方 JSDoc 示例都有简单的文档字符串，如下所示：

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

问题是，在现实生活中的文档中，您通常会有更长的文档字符串：

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

但由于大多数公司（出于合理的可读性原因）都有行长度限制，因此上述内容通常是不可接受的。但是，我想不通的是 "right" 拆分这些行的方法应该是什么。

我能做到：

/**
 * @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 行的 proper/official/canonical 方式是什么（在代码中，而不是在生成的 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 风格指南： http://google.github.io/styleguide/javascriptguide.xml?showone=Comments#Comments

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

我建议使用缩进方法 - 我认为它很好地兼顾了可读性和不使用极短的行。

JSDoc 长行的 proper/canonical 格式是什么？

What is the proper/canonical formatting of long JSDoc lines?

jsdoc