mirror of
https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor
synced 2024-09-25 11:16:51 +00:00
62aeb254d9
Refactored the (previously unused) eg-iframe file to be a template with 2 placeholders for script and styles. The previous version was just the basic version to execute javascript code, but that's not good enough since we need a whole bunch of classes to be loaded. A bash file processes the template into proper html, with the help of the makeStaticLoader maintenance script we already had. Updated demo.css, cleaned up redundant properties restyled slightly to be more like the Vector skin and less "raw". Fixed default $IP path in makeStaticLoader.php to work with simple mediawiki core installs having the extension in the regular extensions directory, and prefixed __DIR__ so it doesn't rely on the directory you call it from. Change-Id: Ic789121dfeca08d9db69564d2ad2e52b3fa45de9
89 lines
2.1 KiB
Markdown
89 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.
|
|
* @returns {Type} Optional text.
|
|
|
|
### 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
|