wikimedia/mediawiki-extensions-VisualEditor

mirror of https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor synced 2024-11-25 14:56:20 +00:00

Timo Tijhof 4e64187beb Document and clean up events in all the things

* 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

2013-03-20 09:58:27 -07:00

2.1 KiB

Raw Blame History

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

2.1 KiB Raw Blame History