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.