mirror of
https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor
synced 2024-11-24 22:35:41 +00:00
8a2b55321c
CODING.md * Document the procedure for adding a new javascript class ve.dm.MWExternalLinkAnnotation.js ve.dm.MWInternalLinkAnnotation.js ve.dm.ElementLinearData.js ve.dm.LinearData.js * Add whitespace line before preformatted code to fix a rendering bug Change-Id: I54443ea3d4799328655d279f379d4ddc176c50a0
109 lines
2.9 KiB
Markdown
109 lines
2.9 KiB
Markdown
# VisualEditor Code Guidelines
|
|
|
|
We inherit the code structure (about whitespace, naming and comments) conventions
|
|
from MediaWiki. See [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}`).
|
|
|
|
### Generate documentation
|
|
|
|
#### Gem (Mac OS X)
|
|
Ruby ships with OSX but may be outdated. Use [Homebrew](http://mxcl.github.com/homebrew/):
|
|
```
|
|
$ brew install ruby
|
|
```
|
|
|
|
If you've never used `gem` before, don't forget to add the gem's bin to your `PATH` ([howto](http://stackoverflow.com/a/14138490/319266)).
|
|
|
|
#### Install
|
|
Once you have gem, installing [JSDuck](https://github.com/senchalabs/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](https://github.com/senchalabs/jsduck/wiki/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).
|