82

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.

machineghost
  • 33,529
  • 30
  • 159
  • 234

1 Answers1

107

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: https://google.github.io/styleguide/jsguide.html#jsdoc-line-wrapping

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 clarity of the comment context and readability (not having extremely short lines)

saraf.gahl
  • 1,429
  • 1
  • 10
  • 13
  • For anyone wondering what the size of the indentation should be from the Google Javascript Style Guide: `If you have to line break a block tag, you should treat this as breaking a code statement and indent it four spaces.` Answer: "four spaces" Follow up: Has anyone checked to see if either approach is compatible with JSDoc? – mrjake101 Apr 15 '22 at 11:42
  • 1
    Note that the link to Google JavaScript Style Guide changed since this answer, and the correct now is: https://google.github.io/styleguide/jsguide.html#jsdoc-line-wrapping Also, the wording has been clarified, so the previous comment is also now clearly stated in the Guide: `Line-wrapped block tags are indented four spaces.` (I tried to edit the answer but S.O. doesn't allow me, saying "*Suggested edit queue is full*") – j1elo Oct 10 '22 at 12:11
  • Both methods work fine in vscode. – Michael Cox Nov 22 '22 at 19:47