When we create the examples, we know exactly which specific `ol.…` symbols
we `goog.require(…)`. We can create links to the API documentation of these
symbols automatically.
The augmentExamples just adds metadata to the example markup files. If we also want to support example markdown files, we can use the metalsmith-markdown plugin before this one.
This task publishes an existing tag to the npm registry. To publish a new release, create a commit that updates the version number in package.json (e.g. to "3.1.0"). Then create a tag, push to GitHub, and run the publish task. Assuming "openlayers" is the remote for the canonical repo, this would look like the following:
git tag -a v3.1.0 -m "3.1.0"
git push --tags openlayers
./tasks/publish.sh 3.1.0
The task creates a build for each of the `PROFILES` in `publish.sh` (these correspond to `.json` files in the `config` directory). Builds are generated in the `dist` directory. Our `package.json` specifies `dist/ol.js` as the "main" build. So when people use a module loader to `require('openlayers')`, they get the full build. It is also possible to load a debug build (e.g. `require('openlayers/dist/ol-debug')`), and we can publish additional builds by adding `config` files and updating `PROFILES` in `publish.sh`.
The `.npmignore` file determines what is *not* included in the package (note that `node_modules` are always ignored). So if additional items are added to `.gitignore` that should not be included in the npm package, they need to go in `.npmignore` as well (ideally, we don't need to generate anything else outside of the `build` directory that doesn't belong in the package).
When concatenating the Closure Library, base.js creates a new `goog` object if there is not already one in scope. Later, `goog.global` is assigned the value of `this`. Calls to `goog.provide` create "namespace" objects by assigning to `goog.global`. To ensure that `goog` is the same as `goog.global.goog`, we need to create a new `goog` object in the scope of base.js and assign it to `this.goog`.
CommonJS style modules will either assign `exports` to `module` or will assign properties to `exports`. This allows us to work with either style:
module.exports = Foo;
or
exports.Foo = Foo;
Support for additional properties that are assigned to `exports` (or non-function values assigned to `module.exports`) will likely take additional typedef work in the wrapper.
