长JSDoc行的正确/规范格式是什么? [英] What is the proper/canonical formatting of long JSDoc lines?

问题描述

所有官方JSDoc示例都具有简单的文档字符串，如下所示:

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.

我可以做到:

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

所以我的问题是，格式化长@param行(在代码中，而不是在生成的JSDoc中)的正确/正式/规范方式是什么?或者实际上是关于此问题的任何长注释行.

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中有两种处理换行符的正确方法.第一种，显然是由Google使用的，是在第一种之后缩进行:

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

这来自《 Google Javascript样式指南》: http://google.github.io/styleguide/javascriptguide.xml?showone=Comments#Comments

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

第二个基于JSDoc源自JavaDoc的事实，这与您的第二个示例类似.有关JavaDoc示例的信息，请参见以下链接: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide

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.

这篇关于长JSDoc行的正确/规范格式是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！