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.
2018-05-10 17:14:17 +02:00
parent 1e0086460b
commit e810387956
17 changed files with 66 additions and 61 deletions
--- a/config/jsdoc/api/conf.json
+++ b/config/jsdoc/api/conf.json
@@ -1,6 +1,7 @@
 {
  "opts": {
-    "recurse": true
+    "recurse": true,
+    "template": "config/jsdoc/api/template"
  },
  "tags": {
    "allowUnknownTags": true
--- a/config/jsdoc/api/index.md
+++ b/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>
-[Overview](ol.Map.html)<br>
-[Creation](ol.Map.html#Map)<br>
-[Events](ol.MapBrowserEvent.html)</td>
+<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](module-ol_Map-Map.html)<br>
+[Creation](module-ol_Map-Map.html#Map)<br>
+[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>
-<td><p>Layers are lightweight containers that get their data from [sources](ol.source.html).</p>
-[ol.layer.Tile](ol.layer.Tile.html)<br>
-[ol.layer.Image](ol.layer.Image.html)<br>
-[ol.layer.Vector](ol.layer.Vector.html)<br>
-[ol.layer.VectorTile](ol.layer.VectorTile.html)</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](module-ol_source_Source-Source.html).</p>
+[layer/Tile](module-ol_layer_Tile-TileLayer.html)<br>
+[layer/Image](module-ol_layer_Image-ImageLayer.html)<br>
+[layer/Vector](module-ol_layer_Vector-VectorLayer.html)<br>
+[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>
-[All controls](ol.control.html)
+<td>[Map default controls](module-ol_control_util.html#.defaults)<br>
+[All controls](module-ol_control_Control-Control.html)
 </td>
 <td>
-[Map default interactions](ol.interaction.html#.defaults)<br>
-Interactions for [vector features](ol.Feature.html)
-<ul><li>[ol.interaction.Select](ol.interaction.Select.html)</li>
-<li>[ol.interaction.Draw](ol.interaction.Draw.html)</li>
-<li>[ol.interaction.Modify](ol.interaction.Modify.html)</li></ul>
-[All interactions](ol.interaction.html)</td>
-<td>[Tile sources](ol.source.Tile.html) for [ol.layer.Tile](ol.layer.Tile.html)
-<br>[Image sources](ol.source.Image.html) for [ol.layer.Image](ol.layer.Image.html)
-<br>[Vector sources](ol.source.Vector.html) for [ol.layer.Vector](ol.layer.Vector.html)
-<br>[Vector tile sources](ol.source.VectorTile.html) for [ol.layer.VectorTile](ol.layer.VectorTile.html)
-<br>[Formats](ol.format.Feature.html) for reading/writing vector data
-<br>[ol.format.WMSCapabilities](ol.format.WMSCapabilities.html)</td></tr>
+[Map default interactions](module-ol_interaction.html#~defaults)<br>
+Interactions for [vector features](module-ol_Feature-Feature.html)
+<ul><li>[interaction/Select](module-ol_interaction_Select-Select.html)</li>
+<li>[interaction/Draw](module-ol_interaction_Draw-Draw.html)</li>
+<li>[interaction/Modify](module-ol_interaction_Modify-Modify.html)</li></ul>
+[All interactions](module-ol_interaction_Interaction-Interaction.html)</td>
+<td>[Tile sources](module-ol_source_Tile-TileSource.html) for [layer/Tile](module-ol_layer_Tile-TileLayer.html)
+<br>[Image sources](module-ol_source_Image-ImageSource.html) for [layer/Image](module-ol_layer_Image-ImageLayer.html)
+<br>[Vector sources](module-ol_source_Vector-VectorSource.html) for [layer/Vector](module-ol_layer_Vector-VectorLayer.html)
+<br>[Vector tile sources](module-ol_source_VectorTile-VectorTile.html) for [layer/VectorTile](module-ol_layer_VectorTile-VectorTileLayer.html)
+<br>[Formats](module-ol_format_Feature-FeatureFormat.html) for reading/writing vector data
+<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>
-[ol.proj](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>
+<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](module-ol_proj.html)</td>
+<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.Overlay](ol.Overlay.html)<br></td>
+[ol/Geolocation](module-ol_Geolocation.html)<br>
+[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
-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.
+*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.
--- a/config/jsdoc/api/plugins/api.js
+++ b/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)) {
--- a/config/jsdoc/api/plugins/default-export.js
+++ b/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.
--- a/config/jsdoc/api/plugins/observable.js
+++ b/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);
        }
--- a/config/jsdoc/api/template/publish.js
+++ b/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({
--- a/config/jsdoc/api/template/tmpl/container.tmpl
+++ b/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>
--- a/config/jsdoc/api/template/tmpl/navigation.tmpl
+++ b/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)) { ?>
--- a/config/jsdoc/api/template/tmpl/observables.tmpl
+++ b/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>
--- a/package.json
+++ b/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": {
--- a/src/ol/ObjectEventType.js
+++ b/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'
--- a/src/ol/layer/Base.js
+++ b/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
--- a/src/ol/layer/Heatmap.js
+++ b/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.
 *
--- a/src/ol/layer/Image.js
+++ b/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.
 *
--- a/src/ol/layer/Tile.js
+++ b/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.
 *
--- a/src/ol/layer/Vector.js
+++ b/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.
 *
--- a/src/ol/layer/VectorTile.js
+++ b/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.
 *