Fix some JSDoc issues

Also makes a few minor changes to the template, so it can be used until
we have a new doc generation process. JSDoc output is written to
build/apidoc.

config/jsdoc/api/conf.json

@@ -1,6 +1,7 @@
 {
   "opts": {
-    "recurse": true
+    "recurse": true,
+    "template": "config/jsdoc/api/template"
   },
   "tags": {
     "allowUnknownTags": true

config/jsdoc/api/index.md

@@ -1,43 +1,43 @@
 <table><tr>
 <th width="33.3%">Map</th><th width="33.3%">View</th><th width="33.3%">Layers</th>
 </tr><tr>
-<td><p>A [map](ol.Map.html) is made of [layers](ol.layer.html), a [view](ol.View.html) to visualize them, [interactions](ol.interaction.html) to modify map content and [controls](ol.control.html) with UI components.</p>
+<td><p>A [map](module-ol_Map-Map.html) is made of [layers](module-ol_layer_Base-BaseLayer.html), a [view](module-ol_View-View.html) to visualize them, [interactions](module-ol_interaction_Interaction-Interaction.html) to modify map content and [controls](module-ol_control_Control-Control.html) with UI components.</p>
-[Overview](ol.Map.html)<br>
+[Overview](module-ol_Map-Map.html)<br>
-[Creation](ol.Map.html#Map)<br>
+[Creation](module-ol_Map-Map.html#Map)<br>
-[Events](ol.MapBrowserEvent.html)</td>
+[Events](module-ol_MapBrowserEvent-MapBrowserEvent.html)</td>
 <td><p>The view manages the visual parameters of the map view, like resolution or rotation.</p>
-[ol.View](ol.View.html) with center, projection, resolution and rotation</td>
+[View](module-ol_View-View.html) with center, projection, resolution and rotation</td>
-<td><p>Layers are lightweight containers that get their data from [sources](ol.source.html).</p>
+<td><p>Layers are lightweight containers that get their data from [sources](module-ol_source_Source-Source.html).</p>
-[ol.layer.Tile](ol.layer.Tile.html)<br>
+[layer/Tile](module-ol_layer_Tile-TileLayer.html)<br>
-[ol.layer.Image](ol.layer.Image.html)<br>
+[layer/Image](module-ol_layer_Image-ImageLayer.html)<br>
-[ol.layer.Vector](ol.layer.Vector.html)<br>
+[layer/Vector](module-ol_layer_Vector-VectorLayer.html)<br>
-[ol.layer.VectorTile](ol.layer.VectorTile.html)</td>
+[layer/VectorTile](module-ol_layer_VectorTile-VectorTileLayer.html)</td>
 </tr><tr>
 <th>Controls</th><th>Interactions</th><th>Sources and formats</th>
 </tr><tr>
-<td>[Map default controls](ol.control.html#.defaults)<br>
+<td>[Map default controls](module-ol_control_util.html#.defaults)<br>
-[All controls](ol.control.html)
+[All controls](module-ol_control_Control-Control.html)
 </td>
 <td>
-[Map default interactions](ol.interaction.html#.defaults)<br>
+[Map default interactions](module-ol_interaction.html#~defaults)<br>
-Interactions for [vector features](ol.Feature.html)
+Interactions for [vector features](module-ol_Feature-Feature.html)
-<ul><li>[ol.interaction.Select](ol.interaction.Select.html)</li>
+<ul><li>[interaction/Select](module-ol_interaction_Select-Select.html)</li>
-<li>[ol.interaction.Draw](ol.interaction.Draw.html)</li>
+<li>[interaction/Draw](module-ol_interaction_Draw-Draw.html)</li>
-<li>[ol.interaction.Modify](ol.interaction.Modify.html)</li></ul>
+<li>[interaction/Modify](module-ol_interaction_Modify-Modify.html)</li></ul>
-[All interactions](ol.interaction.html)</td>
+[All interactions](module-ol_interaction_Interaction-Interaction.html)</td>
-<td>[Tile sources](ol.source.Tile.html) for [ol.layer.Tile](ol.layer.Tile.html)
+<td>[Tile sources](module-ol_source_Tile-TileSource.html) for [layer/Tile](module-ol_layer_Tile-TileLayer.html)
-<br>[Image sources](ol.source.Image.html) for [ol.layer.Image](ol.layer.Image.html)
+<br>[Image sources](module-ol_source_Image-ImageSource.html) for [layer/Image](module-ol_layer_Image-ImageLayer.html)
-<br>[Vector sources](ol.source.Vector.html) for [ol.layer.Vector](ol.layer.Vector.html)
+<br>[Vector sources](module-ol_source_Vector-VectorSource.html) for [layer/Vector](module-ol_layer_Vector-VectorLayer.html)
-<br>[Vector tile sources](ol.source.VectorTile.html) for [ol.layer.VectorTile](ol.layer.VectorTile.html)
+<br>[Vector tile sources](module-ol_source_VectorTile-VectorTile.html) for [layer/VectorTile](module-ol_layer_VectorTile-VectorTileLayer.html)
-<br>[Formats](ol.format.Feature.html) for reading/writing vector data
+<br>[Formats](module-ol_format_Feature-FeatureFormat.html) for reading/writing vector data
-<br>[ol.format.WMSCapabilities](ol.format.WMSCapabilities.html)</td></tr>
+<br>[format/WMSCapabilities](module-ol_format_WMSCapabilities-WMSCapabilities.html)</td></tr>
 <tr><th>Projections</th><th>Observable objects</th><th>Other components</th></tr>
-<tr><td><p>All coordinates and extents need to be provided in view projection (default: EPSG:3857). To transform, use [ol.proj.transform()](ol.proj.html#.transform) and [ol.proj.transformExtent()](ol.proj.html#.transformExtent).</p>
+<tr><td><p>All coordinates and extents need to be provided in view projection (default: EPSG:3857). To transform, use [proj.transform()](module-ol_proj.html#.transform) and [proj.transformExtent()](module-ol_proj.html#.transformExtent).</p>
-[ol.proj](ol.proj.html)</td>
+[ol/proj](module-ol_proj.html)</td>
-<td><p>Changes to all [ol.Objects](ol.Object.html) can be observed by calling the [object.on('propertychange')](ol.Object.html#on) method.  Listeners receive an [ol.Object.Event](ol.Object.Event.html) with information on the changed property and old value.</p>
+<td><p>Changes to all [ol/Object](module-ol_Object-BaseObject.html)s can be observed by calling the [object.on('propertychange')](module-ol_Object-BaseObject.html#on) method.  Listeners receive an [ol/Object~ObjectEvent](module-ol_Object-ObjectEvent.html) with information on the changed property and old value.</p>
 <td>
-[ol.Geolocation](ol.Geolocation.html)<br>
+[ol/Geolocation](module-ol_Geolocation.html)<br>
-[ol.Overlay](ol.Overlay.html)<br></td>
+[ol/Overlay](module-ol_Overlay-Overlay.html)<br></td>
 </tr></table>
 
 &nbsp;
@@ -52,11 +52,4 @@ The OpenLayers API consists of
 
 Within a major release series, the API will not be changed.  Any changes to the API will be accompanied by a new major release.
 
-*Note*: The API change policy does not cover CSS class names that are used to style the
+*Note*: The API change policy does not cover CSS class names that are used to style the OpenLayers UI. It also does not cover any typedefs and enums.
-OpenLayers UI.
-
-*Note for Closure Compiler users compiling their application code together with OpenLayers*:
-The names of types other than those in the list above (e.g. `ol.Coordinate`) are subject to change. It
-is therefore recommended to either use the resolved type as listed in the API docs (e.g.
-`Array.<number>` instead of `ol.Coordinate`), or pay attention to the upgrade notes, which will list
-the changes for those types.

config/jsdoc/api/plugins/api.js

@@ -76,15 +76,12 @@ function extractTypes(item) {
 }
 
 function includeTypes(doclet) {
-  if (doclet.params && doclet.kind != 'class') {
+  if (doclet.params) {
     doclet.params.forEach(extractTypes);
   }
   if (doclet.returns) {
     doclet.returns.forEach(extractTypes);
   }
-  if (doclet.isEnum) {
-    types[doclet.meta.code.name] = true;
-  }
   if (doclet.type && doclet.meta.code.type == 'MemberExpression') {
     extractTypes(doclet);
   }
@@ -131,6 +128,10 @@ exports.handlers = {
         continue;
       }
       if (doclet.kind == 'module' && doclet.longname in modules) {
+        // Document all modules that are referenced by the API
+        continue;
+      }
+      if (doclet.isEnum) {
         continue;
       }
       if (doclet.kind == 'class' && api.some(hasApiMembers, doclet)) {

config/jsdoc/api/plugins/default-export.js

@@ -22,7 +22,7 @@ function addDefaultExportPath(obj) {
           const lines = file.split('\n');
           let hasDefaultExport = false;
           for (let i = 0, ii = lines.length; i < ii; ++i) {
-            hasDefaultExport = hasDefaultExport || lines[i].indexOf('export default ') == 0;
+            hasDefaultExport = hasDefaultExport || /^export default [^\{]/.test(lines[i]);
             const match = lines[i].match(/^export default ([A-Za-z_$][A-Za-z0-9_$]+);$/);
             if (match) {
               // Use variable name if default export is assigned to a variable.

config/jsdoc/api/plugins/observable.js

@@ -47,7 +47,7 @@ exports.handlers = {
         if (!cls.fires) {
           cls.fires = [];
         }
-        event = 'ol.Object.Event#event:change:' + name;
+        event = 'module:ol/Object~ObjectEvent#event:change:' + name;
         if (cls.fires.indexOf(event) == -1) {
           cls.fires.push(event);
         }

config/jsdoc/api/template/publish.js

@@ -1,4 +1,13 @@
 /*global env: true */
+
+const hasOwnProp = Object.prototype.hasOwnProperty;
+
+// Work around an issue with hasOwnProperty in JSDoc's templateHelper.js.
+//TODO Fix in JSDoc.
+Object.prototype.hasOwnProperty = function(property) {
+  return property in this;
+};
+
 const template = require('jsdoc/lib/jsdoc/template');
 const fs = require('jsdoc/lib/jsdoc/fs');
 const path = require('jsdoc/lib/jsdoc/path');
@@ -9,9 +18,12 @@ const _ = require('underscore');
 const htmlsafe = helper.htmlsafe;
 const linkto = helper.linkto;
 const resolveAuthorLinks = helper.resolveAuthorLinks;
-const hasOwnProp = Object.prototype.hasOwnProperty;
 const outdir = env.opts.destination;
 
+// Work around an issue with hasOwnProperty in JSDoc's templateHelper.js.
+//TODO Fix in JSDoc.
+Object.prototype.hasOwnProperty = hasOwnProp;
+
 let view;
 let data;
 
@@ -192,7 +204,7 @@ function attachModuleSymbols(doclets, modules) {
 function buildNav(members) {
   const nav = [];
   // merge namespaces and classes, then sort
-  const merged = members.namespaces.concat(members.classes);
+  const merged = members.modules.concat(members.classes);
   merged.sort(function(a, b) {
     if (a.longname > b.longname) {
       return 1;
@@ -205,9 +217,9 @@ function buildNav(members) {
   _.each(merged, function(v) {
     // exclude interfaces from sidebar
     if (v.interface !== true) {
-      if (v.kind == 'namespace') {
+      if (v.kind == 'module') {
         nav.push({
-          type: 'namespace',
+          type: 'module',
           longname: v.longname,
           name: v.name,
           members: find({

config/jsdoc/api/template/tmpl/container.tmpl

@@ -20,12 +20,10 @@
     <br>
     <?js if (doc.stability || doc.kind == 'namespace') {
       var ancestors = doc.ancestors.map(a => a.replace(/>\./g, '>').replace(/\.</g, '<')).join('/');
-      var name = doc.name.toLowerCase();
       var parts = [];
       if (ancestors) {
-        parts.push(ancestors);
+        parts.push(ancestors.split('~').shift());
       }
-      parts.push(name);
       var importPath = parts.join('/');
     ?>
     <pre class="prettyprint source"><code>import <?js= doc.name ?> from '<?js= importPath ?>';</code></pre>

config/jsdoc/api/template/tmpl/navigation.tmpl

@@ -11,7 +11,7 @@ var self = this;
     ?>
         <li class="item" data-name="<?js= item.longname ?>">
             <span class="title">
-                <?js= self.linkto(item.longname, item.longname) ?>
+                <?js= self.linkto(item.longname, item.longname.replace('module:', '')) ?>
                 <?js if (item.type === 'namespace' &&
                         (item.members.length + item.typedefs.length + item.methods.length +
                          item.events.length > 0)) { ?>

config/jsdoc/api/template/tmpl/observables.tmpl

@@ -8,7 +8,7 @@
     <th>Name</th>
     <th>Type</th>
     <th>Settable</th>
-    <th><a href="ol.Object.Event.html">ol.Object.Event</a> type</th>
+    <th><a href="module-ol_Object-ObjectEvent.html">ol/Object~ObjectEvent</a> type</th>
     <th class="last">Description</th>
   </tr>
   </thead>

package.json

@@ -23,7 +23,7 @@
     "src-closure": "babel -q --out-dir build/src-closure src/",
     "pretypecheck": "npm run src-closure",
     "typecheck": "node tasks/typecheck",
-    "apidoc": "jsdoc -c config/jsdoc/api/conf.json -d build/apidoc"
+    "apidoc": "jsdoc config/jsdoc/api/index.md -c config/jsdoc/api/conf.json -d build/apidoc"
   },
   "main": "src/ol/index.js",
   "repository": {

src/ol/ObjectEventType.js

@@ -8,7 +8,7 @@
 export default {
   /**
    * Triggered when a property is changed.
-   * @event module:ol/Object~Event#propertychange
+   * @event module:ol/Object~ObjectEvent#propertychange
    * @api
    */
   PROPERTYCHANGE: 'propertychange'

src/ol/layer/Base.js

@@ -28,7 +28,7 @@ import {assign} from '../obj.js';
  * Abstract base class; normally only used for creating subclasses and not
  * instantiated in apps.
  * Note that with {@link module:ol/layer/Base} and all its subclasses, any property set in
- * the options is set as a {@link module:ol/Object property on the layer object, so
+ * the options is set as a {@link module:ol/Object} property on the layer object, so
  * is observable, and has get/set accessors.
  *
  * @constructor

src/ol/layer/Heatmap.js

@@ -58,7 +58,7 @@ const DEFAULT_GRADIENT = ['#00f', '#0ff', '#0f0', '#ff0', '#f00'];
 /**
  * @classdesc
  * Layer for rendering vector data as a heatmap.
- * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject
+ * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject}
  * property on the layer object; for example, setting `title: 'My Title'` in the
  * options means that `title` is observable, and has get/set accessors.
  *

src/ol/layer/Image.js

@@ -30,7 +30,7 @@ import Layer from '../layer/Layer.js';
  * @classdesc
  * Server-rendered images that are available for arbitrary extents and
  * resolutions.
- * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject
+ * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject}
  * property on the layer object; for example, setting `title: 'My Title'` in the
  * options means that `title` is observable, and has get/set accessors.
  *

src/ol/layer/Tile.js

@@ -35,7 +35,7 @@ import {assign} from '../obj.js';
  * @classdesc
  * For layer sources that provide pre-rendered, tiled images in grids that are
  * organized by zoom levels for specific resolutions.
- * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject
+ * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject}
  * property on the layer object; for example, setting `title: 'My Title'` in the
  * options means that `title` is observable, and has get/set accessors.
  *

src/ol/layer/Vector.js

@@ -80,7 +80,7 @@ const Property = {
 /**
  * @classdesc
  * Vector data that is rendered client-side.
- * Note that any property set in the options is set as a {@link }
+ * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject}
  * property on the layer object; for example, setting `title: 'My Title'` in the
  * options means that `title` is observable, and has get/set accessors.
  *

src/ol/layer/VectorTile.js

@@ -91,7 +91,7 @@ export const RenderType = {
 /**
  * @classdesc
  * Layer for vector tile data that is rendered client-side.
- * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject
+ * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject}
  * property on the layer object; for example, setting `title: 'My Title'` in the
  * options means that `title` is observable, and has get/set accessors.
  *