Js/javascript Code Comment Specifications and examples

file Comments

The file comments are located at the very front of the file and should include the following information about the file: Description and version (required) The project address (must) the copyright notice (must) the open source Agreement (required) version number (must) modification time (must), in ISO format (can use sublime Text Insertdate plug-in insert) file comments must all be in English characters and exist in the development and production versions of the file. For example:

/*!

* Jraiser 2 Javascript Library

* waterfall-v1.0.0 (2013-03-15t14:55:51+0800)

* http://jraiser.org/| Released under MIT license

*/

/*!

* kan.56.com-v1.1 (2013-03-08t15:30:32+0800)

* Copyright 2005-2013 56.com

*/

If some open source components are included in the file, they must be described in the file comments. For example:

/*!

* Jraiser 2 Javascript Library

* sizzle-v1.9.1 (2013-03-15t10:07:24+0800)

* http://jraiser.org/| Released under MIT license

*

* Include Sizzle (http://sizzlejs.com/)

*/

General notes

General comments are intended to help developers and readers understand the program better and do not appear in the API documentation. Where the single-line comment begins with "//"; The multiline comment begins with "/*" and ends with "*/". The use of general notes is subject to the following provisions.

Always leave a space after the single-line comment character. For example:

//This is comment

Always leave a space before the Terminator of the multiline comment (to align the asterisk). For example:

/*



*/

Do not write comments at the start of a multiline comment, the line where the Terminator is located. For example:

/*Start



End*/

/*

Here are Line 1

Here are Line 2

*/

Do not write meaningless comments. For example:

//initializes the value variable to 0

varValue = 0;

If a piece of code has functionality that is not implemented or needs to be perfected, a "todo" tag must be added, and a space should be left before and after "Todo". For example:

//TODO unhandled ie6-8 compatibility

functionSetOpacity (node, Val) {

Node.style.opacity = val;

}

Document Comments

The document comments will appear in the API documentation in a predetermined format. It begins with "/**" and ends with "* *", with each line beginning with "*" (all aligned with the first "*" of the start character), and leaving a space between the comment content and the "*". For example:

/**

* Comment

*/

A document comment must contain one or more comment labels.

• @module. To declare a module, use:

  /* *
  
  * Module Description
  
  * @module Module Name
  
  */

  Example:/* *
  
  * Core module provides the most basic and most essential interface
  
  * @module Core
  
  */

@class. To declare a class, use:

/**

* Class Description

* @class class Name

* @constructor

*/

@class must be used with @constructor or @static to mark non-static classes and static classes, respectively.

/**

* Node Collection class

* @class NodeList

* @constructor

* @param {arraylike<element>} Nodes Initialize node

*/

@method. To declare a function or class method, use:

/**

* Method Description

* @method Method Name

* @for class Name

* @param {parameter type} parameter Name argument description

* @return {return value type} return value description

*/

When @for is not specified, this function represents the global or module top-level function. When a function is a static function, @static must be added, and @param must be used when the function has arguments, and @return must be used when the function has a return value.

/**

* Returns the element at the specified position in the current collection

* @method

* @for NodeList

* @param {number} [i=0] position subscript. If negative, the countdown starts from the last element of the collection

* @return {element} specifies elements

*/

@param. Declaring function parameters must be used in conjunction with @method.

The corresponding format is used when the parameter has the following conditions:

[Name of parameter]

Parameters have default values:

[Parameter name = default value]

@property. To declare a class property, use:

/**

* Attribute Description

* @property {Attribute type} property name

*/

Js/javascript Code Comment Specifications and examples