ashatora/openlayers
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #13970 from tschaub/apidoc-updates

Browse Source 
Nicer links in the API docs
This commit is contained in:
Tim Schaub
2022-08-15 17:04:19 -06:00
committed by GitHub
parent c2f1d1bbc7 e566868a5b
commit 7d296a9ffc
13 changed files with 134 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
config/jsdoc/api/index.md
View File

@@ -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>
<a href="module-ol_proj.html">ol/proj</a>
<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>
<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>

116
config/jsdoc/api/template/publish.js
View File

@@ -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;

10
config/jsdoc/api/template/tmpl/container.tmpl
View File

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

2
config/jsdoc/api/template/tmpl/members.tmpl
View File

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

4
config/jsdoc/api/template/tmpl/method.tmpl
View File

@@ -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') { ?>

2
config/jsdoc/api/template/tmpl/observables.tmpl
View File

@@ -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>

2
config/jsdoc/api/template/tmpl/returns.tmpl
View File

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

2
config/jsdoc/api/template/tmpl/type.tmpl
View File

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

2
src/ol/layer/VectorTile.js
View File

@@ -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.
*

4
src/ol/proj/Projection.js
View File

@@ -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.
*/
/**

6
src/ol/render/canvas/Immediate.js
View File

@@ -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.

2
src/ol/source/Vector.js
View File

@@ -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) {

2
src/ol/webgl/Helper.js
View File

@@ -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