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

Jsdoc

Jsdoc Problem Overview


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.

Jsdoc Solutions


Solution 1 - Jsdoc

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.

Attributions

All content for this solution is sourced from the original question on Stackoverflow.

The content on this page is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

Content TypeOriginal AuthorOriginal Content on Stackoverflow
QuestionmachineghostView Question on Stackoverflow
Solution 1 - Jsdocsaraf.gahlView Answer on Stackoverflow