长的 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行(在代码中,而不是在生成的 JSDoc 中)的正确/正式/规范的方法是什么... ... 或者任何真正的长注释行。

12990 次浏览

在 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

第二个示例基于这样一个事实,即 JDoc 是从 JavaDoc 派生出来的,这与第二个示例类似。有关 JavaDoc 示例,请参见以下链接: Http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide

我建议使用缩进方法——我认为这是评论上下文清晰度和可读性(没有非常短的行)之间的一个很好的交叉点