mediawiki-extensions-VisualEditor/CODING.md

VisualEditor Code Guidelines

We inherit the code structure (about whitespace, naming and comments) conventions from MediaWiki. See 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}).

Generate documentation

Gem (Mac OS X)

Ruby ships with OSX but may be outdated. Use Homebrew:

$ brew install ruby

If you've never used gem before, don't forget to add the gem's bin to your PATH (howto).

Install

Once you have gem, installing JSDuck is easy:

$ gem install jsduck

Run

$ cd VisualEditor
$ .docs/generate.sh
# open http://localhost/VisualEditor/docs/

For more options:

$ jsduck --help

Annotations

We use the following annotations. They should be used in the order as they are described here, for consistency. See JSDuck/Tags for more elaborate documentation.

• @class Name (optional, guessed)
• @abstract
• @extends ClassName
• @mixins ClassName
• @constructor
• @private
• @static
• @method name (optional, guessed)
• @template
• @property name (optional, guessed)
• @until Text: Optional text.
• @source Text
• @context {Type} Optional text.
• @param {Type} name Optional text.
• @emits name
• @returns {Type} Optional text.
• @chainable
• @throws {Type}

Types

Special values:

• undefined
• null
• this

Primitive types:

• boolean
• number
• string

Built-in classes:

• Array
• Date
• Function
• RegExp
• Object

Browser classes:

• HTMLElement

jQuery classes:

• jQuery
• jQuery.Event

Add a new javascript class

When a new javascript class is added, the file must be referenced in a number of places before it can be used.

Test files:

• VisualEditor.hooks.php in onResourceLoaderTestModules

Regular files:

• .docs/categories.json in General->Utilities (or somewhere more specific)
• VisualEditor.php in ext.visualEditor.core (or somewhere more specific)
• Run php maintenance/makeStaticLoader.php --target demo --write-file demos/ve/index.php
• Run php maintenance/makeStaticLoader.php --target test --write-file modules/ve/test/index.php

makeStaticLoader.php is a maintenance script to automatically generate an HTML document fragment containing script tags in dependency order (for standalone environments without ResourceLoader).