openlayers/ol3 — pull request #1180 by pagameba (2013-10-28 00:14:02+00:00)
Title: Add jsdoc plugins for stability and observables

This pull request supersedes #1172 and #1174 by combining the stability plugin with an observable plugin and a todo plugin.

The stability plugin, will add a 'not documented' stability level to anything that is not specifically set with the `@stability` tag.

I snagged the bootstrap alert classes and repurposed them for the display style, changing alert to stability to give better control over the display of the levels.

The built-in levels are set in the defaults of the plugin itself, with the ability to override them in the conf.js file. The css changes assume the built-in levels.

* deprecated, uses alert-error style
* experimental, uses alert-warning style
* unstable, uses alert-info style
* stable, uses alert-success style
* frozen, uses alert-success style
* locked, uses alert-success style

I took the levels directly from node.js as discussed. In thinking more about it, I'm not sure I see the point in having stable, frozen and locked - stable seems sufficient to me.

The observable plugin allows documenting class properties annotated with @observable, following similar rules to regular properties for type and name annotations. For instance, ol.View2D might get something like this:

* @observable {ol.Coordinate} center the center of the view
* @observable {ol.proj.Projection} projection the projection of the view
* @observable {number} resolution the resolution of the view
* @observable {number} rotation the rotation of the view in radians

In addition, if the description starts with the word `readonly` then the property is documented as not having a setter. The output contains a section at the same level as members and methods (and before them) with a properties table of these observable properties. The table, as proposed, contains Name, Type, Get (always yes), Set (no for readonly, yes otherwise), Event (change:) and Description (with readonly removed if it was present).

The todo plugin provides temporary support for `@todo stability` and `@todo observable` so that we can begin documenting the API using tags that Plovr won't barf on and eventually replace them with the correct version with Plovr is fixed or replaced.

I cherry-picked the original commit from #1172 for the stability plugin, hope that is okay - I tried to collapse it all into a single commit but my git-fu is not strong enough.