AngularJS评论样式指南

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); };
}

它以斜杠（/）开头，后跟两个两个星号（*），并且每行上都有一个星号。在哪里定义？然后有几个@符号。 Javascript注释以/*或//开头，例如described here，因此此处涉及一些其他样式。我正在寻找对此的描述。...

Answer 1

[好，我要亲自回答。有人在给我this link的答案的评论中被删除了。多亏您，无论您是谁。我正在从此文档剪切和粘贴：

文档注释是用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超链接。此内联标签可在任何可写注释的地方使用，例如在块标签后面的文本中。
• 如果您在文档注释中包含多个段落，请使用

  段落标记分隔各个段落，如图所示。

• 在描述和标签列表之间插入空白注释行，如图所示。
• 第一行以“ @”字符开头的描述结束。每个文档注释只有一个描述块；您不能在块标记后继续描述。
• 最后一行包含结尾注释定界符（* /）注意，与开始注释定界符不同，结尾注释仅包含一个星号。

更多示例，请参见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

很棒的文章。我也在处理其中一些问题...

AngularJS Training in Bangalore

Angular 7 Training in Bangalore