什麼是長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

我會建議使用縮進方法 - 我認爲這是一個良好的可讀性和不具有極短的線之間的交叉。