Merge pull request #8189 from ahocevar/more-apidoc-fixes

More apidoc fixes

config/jsdoc/api/conf.json

@@ -10,12 +10,13 @@
     "includePattern": ".+\\.js(doc)?$",
     "excludePattern": "(^|\\/|\\\\)_",
     "include": [
-      "src"
+      "src/ol"
     ]
   },
   "plugins": [
     "plugins/markdown",
-    "config/jsdoc/api/plugins/default-export",
+    "config/jsdoc/api/plugins/normalize-exports",
+    "config/jsdoc/api/plugins/inline-options",
     "config/jsdoc/api/plugins/events",
     "config/jsdoc/api/plugins/observable",
     "config/jsdoc/api/plugins/api"

config/jsdoc/api/plugins/api.js

@@ -82,6 +82,9 @@ function includeTypes(doclet) {
   if (doclet.returns) {
     doclet.returns.forEach(extractTypes);
   }
+  if (doclet.properties) {
+    doclet.properties.forEach(extractTypes);
+  }
   if (doclet.type && doclet.meta.code.type == 'MemberExpression') {
     extractTypes(doclet);
   }
@@ -131,7 +134,7 @@ exports.handlers = {
         // Document all modules that are referenced by the API
         continue;
       }
-      if (doclet.isEnum) {
+      if (doclet.isEnum || doclet.kind == 'typedef') {
         continue;
       }
       if (doclet.kind == 'class' && api.some(hasApiMembers, doclet)) {

config/jsdoc/api/plugins/inline-options.js

@@ -0,0 +1,49 @@
+/**
+ * @filedesc
+ * Inlines option params from typedefs
+ */
+
+const properties = {};
+
+exports.handlers = {
+
+  /**
+   * Collects all typedefs, keyed by longname
+   * @param {Object} e Event object.
+   */
+  newDoclet: function(e) {
+    if (e.doclet.kind == 'typedef' && e.doclet.properties) {
+      properties[e.doclet.longname] = e.doclet.properties;
+    }
+  },
+
+  /**
+   * Adds `options.*` params for options that match the longname of one of the
+   * collected typedefs.
+   * @param {Object} e Event object.
+   */
+  parseComplete: function(e) {
+    const doclets = e.doclets;
+    for (let i = 0, ii = doclets.length; i < ii; ++i) {
+      const doclet = doclets[i];
+      if (doclet.params) {
+        const params = doclet.params;
+        for (let j = 0, jj = params.length; j < jj; ++j) {
+          const param = params[j];
+          if (param.type && param.type.names) {
+            const type = param.type.names[0];
+            if (type in properties) {
+              param.type.names[0] = type;
+              params.push.apply(params, properties[type].map(p => {
+                const property = Object.assign({}, p);
+                property.name = `${param.name}.${property.name}`;
+                return property;
+              }));
+            }
+          }
+        }
+      }
+    }
+  }
+
+};

config/jsdoc/api/plugins/normalize-exports.js

@@ -26,13 +26,13 @@ function addDefaultExportPath(obj) {
             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.
-              obj[index] = name.replace(module, `${module}~${match[1]}`);
+              obj[index] = name = name.replace(module, `${module}~${match[1]}`);
               return;
             }
           }
           if (hasDefaultExport) {
             // Duplicate last part if default export is not assigned to a variable.
-            obj[index] = name.replace(module, `${module}~${module.split('/').pop()}`);
+            obj[index] = name = name.replace(module, `${module}~${module.split('/').pop()}`);
           }
         }
       });
@@ -40,6 +40,24 @@ function addDefaultExportPath(obj) {
   });
 }
 
+function replaceLinks(comment) {
+  const matches = comment.match(/\{@link [^\} #]+}/g);
+  if (matches) {
+    const modules = matches.map(m => {
+      const mm = m.match(/(module:[^\}]+)}$/);
+      if (mm) {
+        return mm[1];
+      }
+    }).filter(m => !!m);
+    const newModules = modules.concat();
+    addDefaultExportPath(newModules);
+    modules.forEach((module, i) => {
+      comment = comment.replace(module, newModules[i]);
+    });
+  }
+  return comment;
+}
+
 exports.handlers = {
 
   /**
@@ -56,6 +74,17 @@ exports.handlers = {
       const pathArgs = [doclet.meta.path].concat(levelsUp.map(() => '../'));
       moduleRoot = path.resolve.apply(null, pathArgs);
     } else {
+      if (doclet.description) {
+        doclet.description = replaceLinks(doclet.description);
+      }
+      if (doclet.classdesc) {
+        doclet.classdesc = replaceLinks(doclet.classdesc);
+      }
+
+      const module = doclet.longname.split('#').shift();
+      if (module.indexOf('module:') == 0 && module.indexOf('.') !== -1) {
+        doclet.longname = doclet.longname.replace(module, module.replace('.', '~'));
+      }
       if (doclet.augments) {
         addDefaultExportPath(doclet.augments);
       }
@@ -72,14 +101,6 @@ exports.handlers = {
         addDefaultExportPath(doclet.type);
       }
     }
-  },
-
-  /**
-   * Adds `options.*` params for options that match the longname of one of the
-   * collected typedefs.
-   * @param {Object} e Event object.
-   */
-  parseComplete: function(e) {
   }
 
 };

config/jsdoc/api/template/static/scripts/main.js

@@ -85,7 +85,7 @@ $(function () {
     var srcLinks = $('div.tag-source');
     srcLinks.each(function(i, el) {
       var textParts = el.innerHTML.trim().split(', ');
-      var link = 'https://github.com/openlayers/openlayers/blob/v' + currentVersion + '/' +
+      var link = 'https://github.com/openlayers/openlayers/blob/v' + currentVersion + '/src/ol/' +
           textParts[0];
       el.innerHTML = '<a href="' + link + '">' + textParts[0] + '</a>, ' +
           '<a href="' + link + textParts[1].replace('line ', '#L') + '">' +

package.json

@@ -1,6 +1,6 @@
 {
   "name": "openlayers",
-  "version": "4.6.5",
+  "version": "5.0.0-beta.12",
   "description": "Build tools and sources for developing OpenLayers based mapping applications",
   "keywords": [
     "map",
@@ -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 config/jsdoc/api/index.md -c config/jsdoc/api/conf.json -d build/apidoc"
+    "apidoc": "jsdoc config/jsdoc/api/index.md -c config/jsdoc/api/conf.json -P package.json -d build/apidoc"
   },
   "main": "src/ol/index.js",
   "repository": {

src/ol/Map.js

@@ -35,7 +35,7 @@ import CanvasVectorTileLayerRenderer from './renderer/canvas/VectorTileLayer.js'
  *       target: 'map'
  *     });
  *
- * The above snippet creates a map using a {@link module:ol/layer/Tile~Tile} to
+ * The above snippet creates a map using a {@link module:ol/layer/Tile} to
  * display {@link module:ol/source/OSM~OSM} OSM data and render it to a DOM
  * element with the id `map`.
  *

src/ol/PluggableMap.js

@@ -87,7 +87,7 @@ import {create as createTransform, apply as applyTransform} from './transform.js
  * @typedef {Object} MapOptions
  * @property {module:ol/Collection.<module:ol/control/Control>|Array.<module:ol/control/Control>} [controls]
  * Controls initially added to the map. If not specified,
- * {@link module:ol/control~defaults} is used.
+ * {@link module:ol/control/util~defaults} is used.
  * @property {number} [pixelRatio=window.devicePixelRatio] The ratio between
  * physical pixels and device-independent pixels (dips) on the device.
  * @property {module:ol/Collection.<module:ol/interaction/Interaction>|Array.<module:ol/interaction/Interaction>} [interactions]

src/ol/source/VectorTile.js

@@ -59,7 +59,7 @@ import {createXYZ, extentFromProjection, createForProjection} from '../tilegrid.
  * with vector features from the server, it is not meant for feature editing.
  * Features are optimized for rendering, their geometries are clipped at or near
  * tile boundaries and simplified for a view resolution. See
- * {@link module:ol/source/VectorSource} for vector sources that are suitable for feature
+ * {@link module:ol/source/Vector} for vector sources that are suitable for feature
  * editing.
  *
  * @constructor