Shorten long names when creating links

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,8 +156,37 @@ 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>';
 
@@ -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');

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 } ?>
 

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

@@ -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/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 }); ?>