wikimedia/mediawiki-extensions-VisualEditor

mirror of https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor synced 2024-09-24 10:48:42 +00:00

Timo Tijhof 62aeb254d9 Implement inline documentation examples.

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

2013-02-08 17:47:10 -08: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.
@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

2.1 KiB Raw Blame History