This task generates build related metadata for the library based on doc annotations. Since it is about more than writing out exportable symbols, it makes sense to have a more general name.
With this change, the only two remaining generated scripts are build/exports.js and build/test/requireall.js. Both are only required by Plovr. With the Node based build task, a temporary exports.js file is created. The Node based server can be used to run the tests without build/test/requireall.js.
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.
The generate-symbols.js task runs JSDoc on source files. Because this takes a long time (13s) to run on the whole library, the resulting symbols file includes additional metadata to make it possible to do incremental symbol generation on subsequent runs. The 'path' and 'extends' metadata for a symbol are used to determine what needs to be regenerated.
There are cases where a private class may inherit an exportable member (e.g. ol.DebugTile_#getTileCoord comes from ol.Tile#getTileCoord). We want to avoid making these exportable.
This generates info for all symbols annotated with "@todo api" (when Plovr is replaced, this will become "@api"). Generated metadata is written to stdout. A separate process will handle the output.
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.
Tim Schaub
Andreas Hocevar
Frederic Junod
Tom Payne
Antoine Abt
Éric Lemoine
Bruno Binet