This change adds all information that is needed to generate the externs
file to build/info.json, so tasks/generate-externs.js no longer needs
to spawn JSDoc.
The ol-all.json and ol.json build configurations differ only in their use of the manage_closure_dependencies Compiler option. I don't think there is value in running both (there are plenty of other compiler options that we don't exercise in this same way).
Instead of running everything through the Compiler just to remove whitespace, we provide a build that is a simple concatenation of all scripts in dependency order. This build (ol-debug.js) should never be used in production (the same applies to the old ol-whitespace.js build). Instead, the intention is that it be used to aid in debugging during development.
If a `src` config is not provided, by default, all of the library sources are included. There is some special handling in the build task to make sure all library sources are included regardless of the path to the build config. When someone includes a `src` config, path patterns are assumed to be relative to the current working directory (unless overriden with the `cwd` config). So, when you use the `src` config, your config is no longer portable.
Because we don't know if a new or modified file includes changes to the class hierarchy, we regenerate info for all sources any time any one has changed. An alternative would be to generate info first for the new or modified file and then (potentially) regenerate info for more source files in the class hierarchy, but this makes the generate-info.js task far more complicated.
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.
