什么是长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. 
*/ 

这是从谷歌的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

我会建议使用缩进方法 - 我认为这是一个良好的可读性和不具有极短的线之间的交叉。