AngularJS comments style guide

Question

When looking at the source code of Angular it seems there is a certain way how to style the comments. A quick google search does not reveal what rules to follow. What are the guidelines?

For example, a comment for a function looks like this:

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

It starts with a slash (/) and followed by two two asterisks (*) and it has an asterik on every line. Where is that defined? And then there are several @-symbols. Javascript comments starts with /* or //, as described here, so there are some additional styling involved here. I am searching for a description on this....

Answer 1

Ok, I am going to answer this myself. Somebody gave me this link in a comment of an answer that is now deleted. Thanks to you, whoever you are. I am cutting and pasting from this doc:

A doc comment is written in HTML and must precede a class, field, constructor or method declaration. It is made up of two parts -- a description followed by block tags. In this example, the block tags are @param, @return, and @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;
        }
 }

Notes:

• The resulting HTML from running Javadoc is shown below
• Each line above is indented to align with the code below the comment.
• The first line contains the begin-comment delimiter ( /**).
• Starting with Javadoc 1.4, the leading asterisks are optional.
• Write the first sentence as a short summary of the method, as Javadoc automatically places it in the method summary table (and index).
• Notice the inline tag {@link URL}, which converts to an HTML hyperlink pointing to the documentation for the URL class. This inline tag can be used anywhere that a comment can be written, such as in the text following block tags.
• If you have more than one paragraph in the doc comment, separate the paragraphs with a

  paragraph tag, as shown.

• Insert a blank comment line between the description and the list of tags, as shown.
• The first line that begins with an "@" character ends the description. There is only one description block per doc comment; you cannot continue the description following block tags.
• The last line contains the end-comment delimiter ( */) Note that unlike the begin-comment delimiter, the end-comment contains only a single asterisk.

For more examples, see Simple Examples.

So lines won't wrap, limit any doc-comment lines to 80 characters.

Here is what the previous example would look like after running the Javadoc tool:

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

After seeing this post I tried typing '/**' and I got this in vs code editor

Hit enter and I got like this

however, I don't know whether it is given from vs code extension. I think it is a standard way to comment.