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.
The single externs/olx.js file describes all of the "options" objects we accept in our constructors. The @typedef annotations are used by the compiler for type checking. The @type annotations include documentation for individual options and serve as externs when compiling a profile of the library. When compiling an application together with the library, the externs/olx.js file is included as one of the sources to provide the @typedef's without generating externs.
If we want to maintain multiple src/*.externs.js files instead of one large externs/olx.js file, we can. But while we are still using Plovr, it makes for easier build configurations to have one file.
This removes the build tasks that generated the build/src/external/src/externs/types.js and build/src/internal/src/types.js files as those are both replaced by the single externs/olx.js file.
This is needed because the current version of closure compiler we use does not
include externs for valueAsNumber which we now use in ol.dom.Input.
So this backports patch from issue:
https://code.google.com/p/closure-compiler/issues/detail?id=1060
This patch should be reverted when the next closure compiler release is out
with valueAsNumber externs.
