Merge pull request #13970 from tschaub/apidoc-updates

Nicer links in the API docs

config/jsdoc/api/index.md

@@ -73,8 +73,8 @@
     <div class="card h-100 bg-light">
       <div class="card-body">
         <h4 class="card-title">Projections</h4>
-          <p>All coordinates and extents need to be provided in view projection (default: EPSG:3857). To transform coordinates from and to geographic, use <a href="module-ol_proj.html#.fromLonLat">ol/proj#fromLonLat()</a> and <a href="module-ol_proj.html#.toLonLat">ol/proj#toLonLat()</a>. For extents and other projections, use <a href="module-ol_proj.html#.transformExtent">ol/proj#transformExtent()</a> and <a href="module-ol_proj.html#.transform">ol/proj#transform()</a>.<p>
+          <p>All coordinates and extents need to be provided in view projection (default: EPSG:3857). To transform coordinates from and to geographic, use <a href="module-ol_proj.html#.fromLonLat">fromLonLat()</a> and <a href="module-ol_proj.html#.toLonLat">toLonLat()</a>. For extents and other projections, use <a href="module-ol_proj.html#.transformExtent">transformExtent()</a> and <a href="module-ol_proj.html#.transform">transform()</a>.</p>
-          <a href="module-ol_proj.html">ol/proj</a>
+          <p>Find these functions and more in the <a href="module-ol_proj.html">ol/proj</a> module.</p>
       </div>
     </div>
   </div>
@@ -82,7 +82,7 @@
     <div class="card h-100 bg-light">
       <div class="card-body">
         <h4 class="card-title">Observable objects</h4>
-        <p>Changes to all <a href="module-ol_Object-BaseObject.html">ol/Object</a>s can be observed by calling the <a href="module-ol_Object-BaseObject.html#on">object.on('propertychange')</a> method.  Listeners receive an <a href="module-ol_Object.ObjectEvent.html">ol/Object.ObjectEvent</a> with information on the changed property and old value.</p>
+        <p>Changes to all <a href="module-ol_Object-BaseObject.html">Object</a>s can be observed by calling the <a href="module-ol_Object-BaseObject.html#on">object.on('propertychange')</a> method.  Listeners receive an <a href="module-ol_Object.ObjectEvent.html">ObjectEvent</a> with information on the changed property and old value.</p>
       </div>
     </div>
   </div>

config/jsdoc/api/template/publish.js

@@ -17,7 +17,6 @@ const taffy = require('taffydb').taffy;
 const handle = require('jsdoc/lib/jsdoc/util/error').handle;
 const helper = require('jsdoc/lib/jsdoc/util/templateHelper');
 const htmlsafe = helper.htmlsafe;
-const linkto = helper.linkto;
 const resolveAuthorLinks = helper.resolveAuthorLinks;
 const outdir = env.opts.destination;
 
@@ -32,6 +31,78 @@ function find(spec) {
   return helper.find(data, spec);
 }
 
+function getShortName(longname) {
+  if (!longname.includes('module:ol/')) {
+    return longname;
+  }
+  if (longname.includes('|')) {
+    return longname;
+  }
+  if (longname.includes('<')) {
+    return longname;
+  }
+  return longname.split(/[\~\.#\:]/).pop();
+}
+
+function linkto(longname, linkText, cssClass, fragmentId) {
+  if (linkText) {
+    return helper.linkto(longname, linkText, cssClass, fragmentId);
+  }
+
+  if (!longname.includes('module:ol/')) {
+    return helper.linkto(longname, linkText, cssClass, fragmentId);
+  }
+
+  // check for `Array<foo|bar>` types (but allow `Array<foo>|Array<bar>` types)
+  let openBrackets = 0;
+  let parseTypes = false;
+  for (const c of longname) {
+    if (c === '<') {
+      openBrackets += 1;
+      continue;
+    }
+    if (c === '>') {
+      openBrackets -= 1;
+      continue;
+    }
+    if (openBrackets > 0 && c === '|') {
+      parseTypes = true;
+      break;
+    }
+  }
+  if (parseTypes) {
+    // collections or generics with unions get parsed by catharsis and
+    // will unfortunamely include long module:ol/foo names
+    return helper.linkto(longname, '', cssClass, fragmentId);
+  }
+
+  // handle union types
+  if (longname.includes('|')) {
+    return longname
+      .split('|')
+      .map((part) => linkto(part, '', cssClass, fragmentId))
+      .join(' | ');
+  }
+
+  const match = longname.match(/(.+?)\.?<(.+)>$/);
+  // handle generics and collections
+  if (match) {
+    return (
+      linkto(match[1], '', cssClass, fragmentId) +
+      '<' +
+      linkto(match[2], '', cssClass, fragmentId) +
+      '>'
+    );
+  }
+
+  return helper.linkto(
+    longname,
+    htmlsafe(getShortName(longname)),
+    cssClass,
+    fragmentId
+  );
+}
+
 function tutoriallink(tutorial) {
   return helper.toTutorial(tutorial, null, {
     tag: 'em',
@@ -85,15 +156,44 @@ function addSignatureParams(f) {
   f.signature = (f.signature || '') + '(' + params.join(', ') + ')';
 }
 
+/**
+ * Copied from https://github.com/jsdoc/jsdoc/blob/main/packages/jsdoc/lib/jsdoc/util/templateHelper.js
+ * Modified to call our own `linkto` to shorten names.
+ * @param {Object} doclet The doclet.
+ * @param {Array} [doclet.yields] The returns.
+ * @param {Array} [doclet.returns] The returns.
+ * @param {string} cssClass The css class.
+ * @return {Array} The returns.
+ */
+function getSignatureReturns({yields, returns}, cssClass) {
+  let returnTypes = [];
+
+  if (yields || returns) {
+    (yields || returns).forEach((r) => {
+      if (r && r.type && r.type.names) {
+        if (!returnTypes.length) {
+          returnTypes = r.type.names;
+        }
+      }
+    });
+  }
+
+  if (returnTypes && returnTypes.length) {
+    returnTypes = returnTypes.map((r) => linkto(r, '', cssClass));
+  }
+
+  return returnTypes;
+}
+
 function addSignatureReturns(f) {
-  const returnTypes = helper.getSignatureReturns(f);
+  const returnTypes = getSignatureReturns(f);
 
   f.signature = '<span class="signature">' + (f.signature || '') + '</span>';
 
   if (returnTypes.length) {
     f.signature +=
       '<span class="fa fa-arrow-circle-right"></span><span class="type-signature returnType">' +
-      (returnTypes.length ? '{' + returnTypes.join('|') + '}' : '') +
+      (returnTypes.length ? '{' + returnTypes.join(' | ') + '}' : '') +
       '</span>';
   }
 }
@@ -136,6 +236,13 @@ function getPathFromDoclet(doclet) {
   return filepath;
 }
 
+function preprocessLinks(text) {
+  return text.replaceAll(
+    /\{@link (module:ol\/\S+?)\}/g,
+    (match, longname) => `{@link ${longname} ${getShortName(longname)}}`
+  );
+}
+
 function generate(title, docs, filename, resolveLinks) {
   resolveLinks = resolveLinks === false ? false : true;
 
@@ -150,7 +257,7 @@ function generate(title, docs, filename, resolveLinks) {
   let html = view.render('container.tmpl', docData);
 
   if (resolveLinks) {
-    html = helper.resolveLinks(html); // turn {@link foo} into <a href="foodoc.html">foo</a>
+    html = helper.resolveLinks(preprocessLinks(html)); // turn {@link foo} into <a href="foodoc.html">foo</a>
   }
 
   fs.writeFileSync(outpath, html, 'utf8');
@@ -490,6 +597,7 @@ exports.publish = function (taffyData, opts, tutorials) {
   // add template helpers
   view.find = find;
   view.linkto = linkto;
+  view.getShortName = getShortName;
   view.resolveAuthorLinks = resolveAuthorLinks;
   view.tutoriallink = tutoriallink;
   view.htmlsafe = htmlsafe;

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

@@ -85,7 +85,7 @@
     ?>
         <h3 class="subsection-title">Subclasses</h3>
         <ul><?js subclasses.forEach(function(s) { ?>
-          <li><?js= self.linkto(s.longname, s.longname) ?>
+          <li><?js= self.linkto(s.longname) ?>
             <?js= (s.interface ? '(Interface)' : '') ?>
           </li>
         <?js }); ?></ul>
@@ -95,7 +95,7 @@
         <h3 class="subsection-title">Extends</h3>
 
         <ul><?js doc.augments.forEach(function(a) { ?>
-            <li><?js= self.linkto(a, a) ?></li>
+            <li><?js= self.linkto(a) ?></li>
         <?js }); ?></ul>
     <?js } ?>
 
@@ -103,7 +103,7 @@
         <h3 class="subsection-title">Mixes In</h3>
 
         <ul><?js doc.mixes.forEach(function(a) { ?>
-            <li><?js= self.linkto(a, a) ?></li>
+            <li><?js= self.linkto(a) ?></li>
         <?js }); ?></ul>
     <?js } ?>
 
@@ -111,7 +111,7 @@
         <h3 class="subsection-title">Requires</h3>
 
         <ul><?js doc.requires.forEach(function(r) { ?>
-            <li><?js= self.linkto(r, r) ?></li>
+            <li><?js= self.linkto(r) ?></li>
         <?js }); ?></ul>
     <?js } ?>
 
@@ -162,7 +162,7 @@
         var methods = self.find({kind: 'function', memberof: title === 'Global' ? {isUndefined: true} : doc.longname});
         if (methods && methods.length && methods.forEach) {
     ?>
-        <h3 class="subsection-title">Methods</h3>
+        <h3 class="subsection-title"><?js= doc.kind === 'module' ? 'Functions' : 'Methods' ?></h3>
 
         <dl><?js methods.forEach(function(m) { ?>
             <?js m.parent = doc ?>

config/jsdoc/api/template/tmpl/members.tmpl

@@ -5,7 +5,7 @@ var typeSignature = '';
 
 if (data.type && data.type.names) {
     data.type.names.forEach(function (name) {
-        typeSignature += '<span class="type-signature type ' + name.toLowerCase() + '">{' + self.linkto(name, self.htmlsafe(name)) + '}</span> ';
+        typeSignature += '<span class="type-signature type ' + name.toLowerCase() + '">{' + self.linkto(name) + '}</span> ';
     });
 }
 ?>

config/jsdoc/api/template/tmpl/method.tmpl

@@ -14,7 +14,7 @@ if (/-dev$/.test(version)) {
         <div class="anchor" id="<?js= id ?>">
         </div>
         <h4 class="name">
-            <?js= data.attribs + (kind === 'class' ? 'new ' : '') + (data.scope === 'static' ? longname : name) + (kind !== 'event' ? data.signature : '') ?>
+            <?js= data.attribs + (kind === 'class' ? 'new ' : '') + this.getShortName(longname) + (kind !== 'event' ? data.signature : '') ?>
             <?js if (data.inherited || data.inherits) { ?>
                 <span class="inherited"><?js= this.linkto(data.inherits, 'inherited') ?></span>
             <?js } ?>
@@ -56,7 +56,7 @@ if (/-dev$/.test(version)) {
 
     <?js if (data['this']) { ?>
         <h5>This:</h5>
-        <ul><li><?js= this.linkto(data['this'], data['this']) ?></li></ul>
+        <ul><li><?js= this.linkto(data['this']) ?></li></ul>
     <?js } ?>
 
     <?js if (data.stability || kind !== 'class') { ?>

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

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

config/jsdoc/api/template/tmpl/returns.tmpl

@@ -52,7 +52,7 @@ if (returns.length > 1) {
             <?js
                 if (ret.type && ret.type.names) {
                     ret.type.names.forEach(function(name, i) { ?>
-                        <?js= self.linkto(name, self.htmlsafe(name)) ?>
+                        <?js= self.linkto(name) ?>
                         <?js if (i < ret.type.names.length-1) { ?> | <?js } ?>
                     <?js });
                 }

config/jsdoc/api/template/tmpl/type.tmpl

@@ -2,6 +2,6 @@
 	var data = obj;
     var self = this;
     data.forEach(function(name, i) { ?>
-<span class="param-type"><?js= self.linkto(name, self.htmlsafe(name)) ?></span>
+<span class="param-type"><?js= self.linkto(name) ?></span>
 <?js if (i < data.length-1) { ?>|<?js } ?>
 <?js }); ?>

src/ol/layer/VectorTile.js

@@ -89,7 +89,7 @@ import {assert} from '../asserts.js';
 /**
  * @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 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/proj/Projection.js

@@ -17,9 +17,9 @@ import {METERS_PER_UNIT} from './Units.js';
  * @property {import("../extent.js").Extent} [worldExtent] The world extent for the SRS.
  * @property {function(number, import("../coordinate.js").Coordinate):number} [getPointResolution]
  * Function to determine resolution at a point. The function is called with a
- * `number` view resolution and a {@link module:ol/coordinate~Coordinate Coordinate} as arguments, and returns
+ * `number` view resolution and a {@link module:ol/coordinate~Coordinate} as arguments, and returns
  * the `number` resolution in projection units at the passed coordinate. If this is `undefined`,
- * the default {@link module:ol/proj.getPointResolution getPointResolution()} function will be used.
+ * the default {@link module:ol/proj.getPointResolution} function will be used.
  */
 
 /**

src/ol/render/canvas/Immediate.js

@@ -31,11 +31,11 @@ import {transformGeom2D} from '../../geom/SimpleGeometry.js';
 
 /**
  * @classdesc
- * A concrete subclass of {@link module:ol/render/VectorContext~VectorContext VectorContext} that implements
+ * A concrete subclass of {@link module:ol/render/VectorContext~VectorContext} that implements
  * direct rendering of features and geometries to an HTML5 Canvas context.
  * Instances of this class are created internally by the library and
  * provided to application code as vectorContext member of the
- * {@link module:ol/render/Event~RenderEvent RenderEvent} object associated with postcompose, precompose and
+ * {@link module:ol/render/Event~RenderEvent} object associated with postcompose, precompose and
  * render events emitted by layers and maps.
  */
 class CanvasImmediateRenderer extends VectorContext {
@@ -600,7 +600,7 @@ class CanvasImmediateRenderer extends VectorContext {
    * Render a feature into the canvas.  Note that any `zIndex` on the provided
    * style will be ignored - features are rendered immediately in the order that
    * this method is called.  If you need `zIndex` support, you should be using an
-   * {@link module:ol/layer/Vector~VectorLayer VectorLayer} instead.
+   * {@link module:ol/layer/Vector~VectorLayer} instead.
    *
    * @param {import("../../Feature.js").default} feature Feature.
    * @param {import("../../style/Style.js").default} style Style.

src/ol/source/Vector.js

@@ -526,7 +526,7 @@ class VectorSource extends Source {
 
   /**
    * Remove all features from the source.
-   * @param {boolean} [fast] Skip dispatching of {@link module:ol/source/Vector.VectorSourceEvent#event:removefeature removefeature} events.
+   * @param {boolean} [fast] Skip dispatching of {@link module:ol/source/Vector.VectorSourceEvent#event:removefeature} events.
    * @api
    */
   clear(fast) {

src/ol/webgl/Helper.js

@@ -268,7 +268,7 @@ function releaseCanvas(key) {
  *
  *   The GPU only receives the data as arrays of numbers. These numbers must be handled differently depending on what it describes (position, texture coordinate...).
  *   Attributes are used to specify these uses. Specify the attribute names with
- *   {@link module:ol/webgl/Helper~WebGLHelper#enableAttributes enableAttributes()} (see code snippet below).
+ *   {@link module:ol/webgl/Helper~WebGLHelper#enableAttributes} (see code snippet below).
  *
  *   Please note that you will have to specify the type and offset of the attributes in the data array. You can refer to the documentation of [WebGLRenderingContext.vertexAttribPointer](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/vertexAttribPointer) for more explanation.
  *   ```js