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

Question

All of the official JSDoc examples have naively simple documentation strings, like the following:

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

The problem is, in real-life documentation you often have longer documentation strings:

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

But since most companies (for legitimate readability reasons) have line length limits, the above often isn't acceptable. However, what I can't figure out is what the "right" way of breaking up those lines should be.

I could do:

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

But that is difficult to read. I could instead do:

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

That looks better, but it can result in a ton of lines, especially if the parameter has a long name:

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

So my question is, what is the proper/official/canonical way of formatting long @param lines (in the code, not in the generated JSDoc) ... or really any long annotation lines for that matter.

Answer 1

There are two proper ways of dealing with line breaks in JSDoc. The first, apparently used by Google, is to indent the lines after the first:

/**  * @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.  */ 

This is from the Google Javascript Style Guide: http://google.github.io/styleguide/javascriptguide.xml?showone=Comments#Comments

The second is based on the fact that JSDoc is derived from JavaDoc, which is similar to your second example. See the following link for JavaDoc examples: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide

I would recommend using the indentation method - I think it is a good cross between readability and not having extremely short lines.