Question

在查看Angular的源代码时，似乎有一种方式如何设置注释的样式。快速google search没有透露要遵循的规则。准则是什么？

例如，函数的注释如下所示：

/**
* when using forEach the params are value, key, but it is often useful to have key, value.
* @param {function(string, *)} iteratorFn
* @returns {function(*, string)}
*/
function reverseParams(iteratorFn) {
  return function(value, key) { iteratorFn(key, value); };
}

以斜杠（/）开头，后跟两个两个星号（*），每行都有一个星号。这定义在哪里？然后有几个@ -symbols。 Javascript评论以/*或//开头，described here，因此此处还涉及其他一些样式。我正在寻找关于这个的描述......

Answer 1

好的，我将自己回答这个问题。有人在评论中给了我this link现在删除的答案。谢谢你，不管你是谁。我正在剪切和粘贴这个文档：

doc注释是用HTML编写的，必须在类，字段，构造函数或方法声明之前。它由两部分组成 - 描述后跟块标记。在此示例中，块标记为@ param，@ return和@see。

/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * <p>
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
 }

注意：

运行Javadoc的resulting HTML如下所示
上面的每一行都缩进以与评论下面的代码对齐。
第一行包含开始 - 评论分隔符（/**）。
从Javadoc 1.4开始，leading asterisks是可选的。
将第一句写为方法的简短摘要，因为Javadoc会自动将其放在方法摘要表（和索引）中。
请注意内联标记{@link URL}，它转换为指向URL类文档的HTML超链接。此内联标记可用于可以编写注释的任何位置，例如在块标记之后的文本中。
如果您在文档评论中有多个段落，请将段落与
段落标记分开，如图所示。
在说明和标签列表之间插入空白注释行，如图所示。
第一行以＆＃34; @＆＃34;开头字符结束描述。每个文档评论只有一个描述块;您无法继续使用块标记进行描述。
最后一行包含结束注释分隔符（* /）请注意，与begin-comment分隔符不同，结束注释只包含一个星号。

有关更多示例，请参阅Simple Examples。

因此，行不会包装，将任何文档注释行限制为80个字符。

以下是运行Javadoc工具后的示例：

getImage

public Image getImage(URL url,
             String name)
Returns an Image object that can then be painted on the screen. The url argument must specify an absolute URL. The name argument is a specifier that is relative to the url argument.

This method always returns immediately, whether or not the image exists. When this applet attempts to draw the image on the screen, the data will be loaded. The graphics primitives that draw the image will incrementally paint on the screen.

Parameters:
url - an absolute URL giving the base location of the image.
name - the location of the image, relative to the url argument.
Returns:
the image at the specified URL.
See Also:
Image

Answer 2

看到这篇文章后，我尝试输入“ / **”，并在vs代码编辑器中得到了它 enter image description here

按Enter，我就这样 enter image description here

但是，我不知道它是否来自vs代码扩展。我认为这是一种标准的评论方式。谢谢。

AngularJS评论风格指南

2 个答案: