From 9c0e2f35d154225da2eafa9648b7041efc6c2f70 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 11 Aug 2022 13:37:00 -0600 Subject: [PATCH 1/6] Shorten long names when creating links --- config/jsdoc/api/template/publish.js | 113 +++++++++++++++++- config/jsdoc/api/template/tmpl/container.tmpl | 8 +- config/jsdoc/api/template/tmpl/members.tmpl | 2 +- config/jsdoc/api/template/tmpl/method.tmpl | 2 +- config/jsdoc/api/template/tmpl/returns.tmpl | 2 +- config/jsdoc/api/template/tmpl/type.tmpl | 2 +- 6 files changed, 118 insertions(+), 11 deletions(-) diff --git a/config/jsdoc/api/template/publish.js b/config/jsdoc/api/template/publish.js index e9a479d893..bac92a51a3 100644 --- a/config/jsdoc/api/template/publish.js +++ b/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` types (but allow `Array|Array` 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 = '' + (f.signature || '') + ''; @@ -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 foo + html = helper.resolveLinks(preprocessLinks(html)); // turn {@link foo} into foo } fs.writeFileSync(outpath, html, 'utf8'); diff --git a/config/jsdoc/api/template/tmpl/container.tmpl b/config/jsdoc/api/template/tmpl/container.tmpl index b9ef45b5ae..4a0b1d4b38 100644 --- a/config/jsdoc/api/template/tmpl/container.tmpl +++ b/config/jsdoc/api/template/tmpl/container.tmpl @@ -85,7 +85,7 @@ ?>

Subclasses

    -
  • +
@@ -95,7 +95,7 @@

Extends

    -
    • +
@@ -103,7 +103,7 @@

Mixes In

    -
    • +
@@ -111,7 +111,7 @@

Requires

    -
    • +
diff --git a/config/jsdoc/api/template/tmpl/members.tmpl b/config/jsdoc/api/template/tmpl/members.tmpl index 19f224e3d5..6412895305 100644 --- a/config/jsdoc/api/template/tmpl/members.tmpl +++ b/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 += '{' + self.linkto(name, self.htmlsafe(name)) + '} '; + typeSignature += '{' + self.linkto(name) + '} '; }); } ?> diff --git a/config/jsdoc/api/template/tmpl/method.tmpl b/config/jsdoc/api/template/tmpl/method.tmpl index 4fdd023627..d09e9276f8 100644 --- a/config/jsdoc/api/template/tmpl/method.tmpl +++ b/config/jsdoc/api/template/tmpl/method.tmpl @@ -56,7 +56,7 @@ if (/-dev$/.test(version)) {
This:
-
+
diff --git a/config/jsdoc/api/template/tmpl/returns.tmpl b/config/jsdoc/api/template/tmpl/returns.tmpl index 41a25b788b..e72ce80907 100644 --- a/config/jsdoc/api/template/tmpl/returns.tmpl +++ b/config/jsdoc/api/template/tmpl/returns.tmpl @@ -52,7 +52,7 @@ if (returns.length > 1) { - + | - + | \ No newline at end of file From 73baef60e313de83d7b8332d347bc0638c029fb2 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 11 Aug 2022 15:39:41 -0600 Subject: [PATCH 2/6] Use short name for exported functions --- config/jsdoc/api/template/publish.js | 1 + config/jsdoc/api/template/tmpl/container.tmpl | 2 +- config/jsdoc/api/template/tmpl/method.tmpl | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/config/jsdoc/api/template/publish.js b/config/jsdoc/api/template/publish.js index bac92a51a3..afe17e1032 100644 --- a/config/jsdoc/api/template/publish.js +++ b/config/jsdoc/api/template/publish.js @@ -597,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; diff --git a/config/jsdoc/api/template/tmpl/container.tmpl b/config/jsdoc/api/template/tmpl/container.tmpl index 4a0b1d4b38..32c34f739e 100644 --- a/config/jsdoc/api/template/tmpl/container.tmpl +++ b/config/jsdoc/api/template/tmpl/container.tmpl @@ -162,7 +162,7 @@ var methods = self.find({kind: 'function', memberof: title === 'Global' ? {isUndefined: true} : doc.longname}); if (methods && methods.length && methods.forEach) { ?> -

Methods

+

diff --git a/config/jsdoc/api/template/tmpl/method.tmpl b/config/jsdoc/api/template/tmpl/method.tmpl index d09e9276f8..c27a741a61 100644 --- a/config/jsdoc/api/template/tmpl/method.tmpl +++ b/config/jsdoc/api/template/tmpl/method.tmpl @@ -14,7 +14,7 @@ if (/-dev$/.test(version)) {

- + From b5b3cb7b18757893685e98ba3fa64605937f4b15 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 11 Aug 2022 15:44:53 -0600 Subject: [PATCH 3/6] Shorter names --- config/jsdoc/api/index.md | 6 +++--- config/jsdoc/api/template/tmpl/observables.tmpl | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/config/jsdoc/api/index.md b/config/jsdoc/api/index.md index c13118ca76..ce3314c838 100644 --- a/config/jsdoc/api/index.md +++ b/config/jsdoc/api/index.md @@ -73,8 +73,8 @@

Projections

-

All coordinates and extents need to be provided in view projection (default: EPSG:3857). To transform coordinates from and to geographic, use ol/proj#fromLonLat() and ol/proj#toLonLat(). For extents and other projections, use ol/proj#transformExtent() and ol/proj#transform().

- ol/proj +

All coordinates and extents need to be provided in view projection (default: EPSG:3857). To transform coordinates from and to geographic, use fromLonLat() and toLonLat(). For extents and other projections, use transformExtent() and transform().

+

Find these functions and more in the ol/proj module.

@@ -82,7 +82,7 @@

Observable objects

-

Changes to all ol/Objects can be observed by calling the object.on('propertychange') method. Listeners receive an ol/Object.ObjectEvent with information on the changed property and old value.

+

Changes to all Objects can be observed by calling the object.on('propertychange') method. Listeners receive an ObjectEvent with information on the changed property and old value.

diff --git a/config/jsdoc/api/template/tmpl/observables.tmpl b/config/jsdoc/api/template/tmpl/observables.tmpl index 50f44a4b34..1098676dbc 100644 --- a/config/jsdoc/api/template/tmpl/observables.tmpl +++ b/config/jsdoc/api/template/tmpl/observables.tmpl @@ -8,7 +8,7 @@ Name Type Settable - ol/Object.ObjectEvent type + ObjectEvent type Description From d23a77bebf073338137dc147db673c55349f605c Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Mon, 15 Aug 2022 16:13:55 -0600 Subject: [PATCH 4/6] Add space around pipe --- config/jsdoc/api/template/publish.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/jsdoc/api/template/publish.js b/config/jsdoc/api/template/publish.js index afe17e1032..082b29dd24 100644 --- a/config/jsdoc/api/template/publish.js +++ b/config/jsdoc/api/template/publish.js @@ -193,7 +193,7 @@ function addSignatureReturns(f) { if (returnTypes.length) { f.signature += '' + - (returnTypes.length ? '{' + returnTypes.join('|') + '}' : '') + + (returnTypes.length ? '{' + returnTypes.join(' | ') + '}' : '') + ''; } } From 1c65ac4c85847d5ecf86dc53760081069cf11e4c Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Mon, 15 Aug 2022 16:58:18 -0600 Subject: [PATCH 5/6] Include : in characters that separate a short name --- config/jsdoc/api/template/publish.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/jsdoc/api/template/publish.js b/config/jsdoc/api/template/publish.js index 082b29dd24..5fe1d54433 100644 --- a/config/jsdoc/api/template/publish.js +++ b/config/jsdoc/api/template/publish.js @@ -41,7 +41,7 @@ function getShortName(longname) { if (longname.includes('<')) { return longname; } - return longname.split(/[\~\.#]/).pop(); + return longname.split(/[\~\.#\:]/).pop(); } function linkto(longname, linkText, cssClass, fragmentId) { From e566868a5b9fb550f266b80723c59c294364d620 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Mon, 15 Aug 2022 16:58:42 -0600 Subject: [PATCH 6/6] Allow short name to be extracted --- src/ol/layer/VectorTile.js | 2 +- src/ol/proj/Projection.js | 4 ++-- src/ol/render/canvas/Immediate.js | 6 +++--- src/ol/source/Vector.js | 2 +- src/ol/webgl/Helper.js | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/ol/layer/VectorTile.js b/src/ol/layer/VectorTile.js index ee19a288a5..f98efc0394 100644 --- a/src/ol/layer/VectorTile.js +++ b/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. * diff --git a/src/ol/proj/Projection.js b/src/ol/proj/Projection.js index 1a4808c6dd..5c76e9202c 100644 --- a/src/ol/proj/Projection.js +++ b/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. */ /** diff --git a/src/ol/render/canvas/Immediate.js b/src/ol/render/canvas/Immediate.js index db24fc488b..5290d0a897 100644 --- a/src/ol/render/canvas/Immediate.js +++ b/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. diff --git a/src/ol/source/Vector.js b/src/ol/source/Vector.js index 40d276927e..aa6c752030 100644 --- a/src/ol/source/Vector.js +++ b/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) { diff --git a/src/ol/webgl/Helper.js b/src/ol/webgl/Helper.js index 99c4057bdb..143d965e4a 100644 --- a/src/ol/webgl/Helper.js +++ b/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