Wiki Navigation

Complete Template

/*
Script: ScriptName.js
	Script description.

License:
	MIT-style license.

Notes:
	ScriptName.js requires an XHTML doctype.
*/

/*
[Private ]Function|Class|Method: MyClass
	MyClass description.

Extends:
	<A>

Implements:
	<D>, <E>, ...

Syntax:
	>var myClass = new MyClass(param1, param2, func1[, optional]);

Arguments:
	param1   - (type) Short description of param1.
	param2   - (object) An object whose structure is defined below.
	func1	- (function) A function example.
	optional - (type, optional: defaults to false) Short description of optional.

	param2 (continued):
		prop1 - (type) Short description of prop1.
		prop2 - (type, optional) Short description of prop2.
		prop3 - (type, optional: defaults to null) Short description of prop3.

	func1 (continued):

		Signature:
			>func1(fnParam1, fnParam2)

		Arguments:
			fnParam1 - (type) Short description of fnParam1.
			fnParam2 - (type) Short description of fnParam2.

Events:
	onSomething - (function) Description. When it gets called.
		Signature:
			>onSomething(fnParam1, fnParam2)

		Arguments:
			fnParam1 - (type) Short description of fnParam1.
			fnParam2 - (type) Short description of fnParam2.

Properties:
	instanceProp - (type) Short description of the instance's property.

Returns:
	(type) Short description.

Example[s]:
	[Title *if more than one example*]
	[language]
		...
	[/language]

Note:
	Any notes.

See Also:
	<A.method>, <B>, <C>, ...
*/

/*
Selector: name
	Selector description.

Usage:
	[Title]

	>':usage'
	[Title]

	[>':usage(x)']

	Variables:
		x - (type) Description of x.

	Example[s]:
		[language]
		   ...
		[/language]

	...

... (see  Method/Function/Class for other) ...

*/

Detail Explanation

File header

The file header is used to describe the file's utility, license, and any notices that the developer should be aware of.

/*
Script: ScriptName.js
	Script description.

License:
	MIT-style license.

Notes:
	ScriptName.js requires an XHTML doctype.
*/

Script: Includes the ScriptName? (i.e. Class.js) and a description. The description should summarize the utility of the file.

License: MooTools uses MIT-style license.

Notes: Notes are warnings, advice, or notices that pertain to the whole script. A typical Note is that the file may require a certain doctype.

Main Documentation

In detail:

Indicates that only put "Private " if the method/class/function in question is private (duh, eh!? :D).

[Private ]

The | means "OR". Therefore there can be only one of the three possible choices.

Class|Method|Function

The tabbing is very important. After the new line on the previous line a tab is required to describe the Class|Method|Function.

	MyClass description.

When a class extends another class, the superclass needs to be documented. If Fx.Styles Extends Fx, then...

Extends:
	<A>, <B>, <C>, ...

becomes

Extends:
	<Fx>

Similarly if a class Implements other classes. The implemented classes need to be documented. If Fx.Styles Implements Events, Chain, and Options then...

Implements:
	<D>, <E>, ...

becomes:

Implements:
	<Events>, <Chain>, <Options>

All Methods, Classes, and Functions have a syntax that the developer should be aware of. If the function returns a value other than the same instance (for chaining) then a var gets created. Furthermore, all arguments that the function may used need to be included exactly as they are used in the code. All optional arguments are encased in brackets (including the separating comma). For example, for the Fx.Style class this:

Syntax:
	>var myClass = new MyClass(param1, param2, func1[, optional]);