mediawiki-extensions-Visual.../CODING.md

# VisualEditor Code Guidelines

We inherit the code structure (about whitespace, naming and comments) conventions
from MediaWiki:
* [Manual:Coding conventions/JavaScript#Code structure](https://www.mediawiki.org/wiki/Manual:Coding_conventions/JavaScript#Code_structure) on mediawiki.org.

## Documentation comments

* End sentences in a full stop.
* Continue sentences belonging to an annotation on the next line, indented with an
  additional space.
* Types in documentation comments should be separated by a pipe character. Use types
  that are listed in the Types section of this document, otherwise use the identifier
  (full path from the global scope) of the constructor function (e.g. `{ve.dm.BranchNode}`).


### Annotations

We use the following annotations. They should be used in the order as they are described
here for consistency.

* @class
* @mixin
* @abstract
* @constructor
* @extends {Type}
* @static
* @method
* @until Text: Optional details.
* @source
* @param {Type} varName Optional description.
* @returns {Type} Optional description.

### Types

Special values:
* undefined
* null
* Infinity
* NaN

Native language types:
* Boolean
* String
* Number
* Object

Native constructors:
* Array
* Date

Browser constructors:
* DOMElement (alias for HTMLElement)

jQuery constructors:
* jQuery
* jQuery.Event
Documentation & clean up * Commands for Sublime: Find: "(\ @[a-z]+) ([^{].) \{(.)\}" Replace: "$1 {$3} $2" Save all && Close all Find: " function(" Replace: " function (" Save all && Close all Find: "Intialization" Replace: "Initialization" Save all && Close all * Consistent use of types (documented in CODING.rm): - Merged {Integer} into {Number}. - Merged {DOM Node} into {DOMElement}. * Remove work-around /jshint newcap: false / from ve.js Calling Object() as a function to to use the internal toObject no longer throws a newcap warning in JSHint. It only does that normal functions now . (e.g. var a = Cap(); or var a = new uncap();) * Add missing annotations (@static, @method, ..). * Remove unused variables * Remove null-assignments to variables that should just be undefined. There's a few variables explicitly set to null whereas they are set a few lines under and not used otherwise (e.g. 'tx' in ve.ce.Surface.prototype.onPaste) Change-Id: I0721a08f8ecd93c25595aedaa1aadb0e08b83799 2012-09-17 13:30:50 +00:00			`# VisualEditor Code Guidelines`

			`We inherit the code structure (about whitespace, naming and comments) conventions`
			`from MediaWiki:`
			`* [Manual:Coding conventions/JavaScript#Code structure](https://www.mediawiki.org/wiki/Manual:Coding_conventions/JavaScript#Code_structure) on mediawiki.org.`

			`## Documentation comments`

			`* End sentences in a full stop.`
			`* Continue sentences belonging to an annotation on the next line, indented with an`
			`additional space.`
			`* Types in documentation comments should be separated by a pipe character. Use types`
			`that are listed in the Types section of this document, otherwise use the identifier`
			(full path from the global scope) of the constructor function (e.g. `{ve.dm.BranchNode}`).


			`### Annotations`

			`We use the following annotations. They should be used in the order as they are described`
			`here for consistency.`

			`* @class`
			`* @mixin`
			`* @abstract`
			`* @constructor`
			`* @extends {Type}`
			`* @static`
			`* @method`
			`* @until Text: Optional details.`
			`* @source`
			`* @param {Type} varName Optional description.`
			`* @returns {Type} Optional description.`

			`### Types`

			`Special values:`
			`* undefined`
			`* null`
			`* Infinity`
			`* NaN`

			`Native language types:`
			`* Boolean`
			`* String`
			`* Number`
			`* Object`

			`Native constructors:`
			`* Array`
			`* Date`

			`Browser constructors:`
			`* DOMElement (alias for HTMLElement)`

			`jQuery constructors:`
			`* jQuery`
			`* jQuery.Event`