mirror of
https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor
synced 2024-11-15 18:39:52 +00:00
4e64187beb
* Document them consistently between secetions Inheritance and
Static Properties under their own (new) section Events.
* Removed any quotes or brackets around the event name in existing
@emit annotations
Search: @emit.*['"{}(){}]
* For every call to this.emit() anywhere, added @emits.
* Fixed all warnings for references to undefined events
(introduced as a result of the previous point).
Event handler parameter documented based on the emit() call
and actual handlers using the event. Usually the latter is
more elaborate.
* Extend coverage of jQuery as needed
(copied from mwcore/maintenance/jsduck/external.js
written by me, hereby implicitly and explicitly released under MIT).
Specifics
* ve.ce.Surface#onContentChange: Fixed type of range from Object to ve.Range.
* ve.ce.SurfaceObserver#poll: Fix syntax for code from {} to `backticks`.
* ve.ui.Toolbar#onContextChange: Doesn't actually emit "clearState" event.
Removed #onClearState in Tool, ButtonTool and DropdownTool.
Bug: 45872
Change-Id: Id879aa769b2c72d86a0322e75dddeb868211ce28
92 lines
2.1 KiB
Markdown
92 lines
2.1 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
|