openlayers/ol3 — pull request #1172 by pagameba (2013-10-25 18:04:34+00:00)
Title: Add jsdoc support for indicating API stability with inline documentation

In preparation for documenting the stability of API features, this PR adds support for indicating API stability via a new jsdoc tag `@stability`. There is a small plugin for jsdoc that adds a new tag, `@stability`, with some ability to enforce specific level names. The templates and css have been updated to include the stability level in the generated documentation.

As written, it will add a 'not documented' stability level to anything that is not specifically set with the `@stability tag`. It should be usable immediately, however, the `@stability` tag cannot be used in the documentation itself until plovr is removed from the build system or updated to allow custom jsdoc tags to be passed through. Note that running `build.py apidoc` will work with @stability tags and linking passes, its just building the source that fails.

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](http://nodejs.org/api/documentation.html#documentation_stability_index) 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.