We no longer add observable annotations to the constructor.
Instead, we just mark getters (and for read/write properties
also setters) with an observable annotation.
To give other plugins access to doclets that are not part of
the API, we have to mark them undocumented instead of removing
them. They will be removed by JSDoc before publishing anyway.
This change adds a stability value to the api annotation, with
'experimental' as default value.
enum, typedef and event annotations are never exportable, but
api annotations are needed there to make them appear in the
docs.
Nested typedefs are no longer inlined recursively, because the
resulting tables get too wide with the current template.
This commit simplifies the exports.js plugin so it only relies
on the stability notes to generate the documentation, which
completely decouples it from the exportable API.
As a rule of thumb, whenever something has an 'api' annotation,
it should also have a 'stability' annotation. A more verbose
documentation of ol3 specific annotation usage is available in
the new 'apidoc/readme.md' file.
This commit also modifies all source files to implement these
usage suggestions.
Also to get rid of regular expression parsing, instead of
collecting exports for observables from the source files, we use
the 'observable' annotations.
This is a temporary measure until Plovr handles custom tags or is replaced in the build system.
Add support for indicating API stability with inline documentation
In preparation for documenting the stability of API features, this commit adds support for indicating API stability via a new jsdoc tag @stability. There is a small plugin for jsdoc that adds a new tag, @stabiility, with some ability to enforce specific level names. The templates and css have been updated to include the stability level in the generated documentation. (+1 squashed commit)
Squashed commits:
[d6bc03d] Add jsdoc plugin for documenting observable properties of a class.
This renames the doc task to apidoc. The apidoc delegates to jsdoc3 currently. We will have additional documentation that is not built by jsdoc3. It makes sense to reserve the more general 'doc' name for building all documentation (not just apidoc).
Peter Robins
Tim Schaub
Andreas Hocevar
Frederic Junod
Paul Spencer
Bart van den Eijnden
Éric Lemoine