问题
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.
回答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.
来源：https://stackoverflow.com/questions/30676286/what-is-the-proper-canonical-formatting-of-long-jsdoc-lines