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.
Without this we get the following warning from the compiler:
JSC_EXPORTED_FUNCTION_UNKNOWN_RETURN_TYPE. Unable to determine return type for exported function ol.control.Control.prototype.handleMapPostrender at ../src/ol/control/control.js line 79 : 51
I'm not sure why explicitely specifying the return type is required here.
