From cc8cffd3244be34abfcdd16eaf67c0d55c2c94c2 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Sat, 12 May 2018 19:17:36 +0200 Subject: [PATCH 1/6] Faster processing by omitting src/index.js --- config/jsdoc/api/conf.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/jsdoc/api/conf.json b/config/jsdoc/api/conf.json index 9c46eba800..714834478b 100644 --- a/config/jsdoc/api/conf.json +++ b/config/jsdoc/api/conf.json @@ -10,7 +10,7 @@ "includePattern": ".+\\.js(doc)?$", "excludePattern": "(^|\\/|\\\\)_", "include": [ - "src" + "src/ol" ] }, "plugins": [ From 554968f8f26129451efcc123f37ca25172829990 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Sat, 12 May 2018 19:18:02 +0200 Subject: [PATCH 2/6] Inline constructor options --- config/jsdoc/api/conf.json | 3 +- config/jsdoc/api/plugins/inline-options.js | 49 ++++++++++++++++++++++ 2 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 config/jsdoc/api/plugins/inline-options.js diff --git a/config/jsdoc/api/conf.json b/config/jsdoc/api/conf.json index 714834478b..0b5b66be93 100644 --- a/config/jsdoc/api/conf.json +++ b/config/jsdoc/api/conf.json @@ -15,7 +15,8 @@ }, "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" diff --git a/config/jsdoc/api/plugins/inline-options.js b/config/jsdoc/api/plugins/inline-options.js new file mode 100644 index 0000000000..02d6cb8ea6 --- /dev/null +++ b/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; + })); + } + } + } + } + } + } + +}; From 6cd6e3cc83e7df4311f7ec24e62e295f9a7d31fc Mon Sep 17 00:00:00 2001 From: ahocevar Date: Sat, 12 May 2018 19:19:26 +0200 Subject: [PATCH 3/6] Normalize module paths to ignore ~/. differences --- ...default-export.js => normalize-exports.js} | 41 ++++++++++++++----- 1 file changed, 31 insertions(+), 10 deletions(-) rename config/jsdoc/api/plugins/{default-export.js => normalize-exports.js} (67%) diff --git a/config/jsdoc/api/plugins/default-export.js b/config/jsdoc/api/plugins/normalize-exports.js similarity index 67% rename from config/jsdoc/api/plugins/default-export.js rename to config/jsdoc/api/plugins/normalize-exports.js index 593f2eceea..a24e767cd5 100644 --- a/config/jsdoc/api/plugins/default-export.js +++ b/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) { } }; From 52465df88a7f2519715221e7e1b6cb44bfe35798 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Sat, 12 May 2018 19:20:11 +0200 Subject: [PATCH 4/6] Also add object properties and non-object typedefs --- config/jsdoc/api/plugins/api.js | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/config/jsdoc/api/plugins/api.js b/config/jsdoc/api/plugins/api.js index 56635004df..eab6a0bf94 100644 --- a/config/jsdoc/api/plugins/api.js +++ b/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)) { From 8657e31b000866cd6094c76a4d42229fe6d30151 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Sat, 12 May 2018 19:20:27 +0200 Subject: [PATCH 5/6] Fix a few doc comment typos --- src/ol/Map.js | 2 +- src/ol/PluggableMap.js | 2 +- src/ol/source/VectorTile.js | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/ol/Map.js b/src/ol/Map.js index 99d5ab3577..a9b1e31f95 100644 --- a/src/ol/Map.js +++ b/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`. * diff --git a/src/ol/PluggableMap.js b/src/ol/PluggableMap.js index a510c66f1d..c6fa638b93 100644 --- a/src/ol/PluggableMap.js +++ b/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.|Array.} [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.|Array.} [interactions] diff --git a/src/ol/source/VectorTile.js b/src/ol/source/VectorTile.js index 0b4e66d8a0..8fbfea3c9b 100644 --- a/src/ol/source/VectorTile.js +++ b/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 From 527331a797e8cb912fa57d3e19367c5611a0dc02 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Sun, 13 May 2018 11:15:31 -0500 Subject: [PATCH 6/6] Make docs work when published --- config/jsdoc/api/template/static/scripts/main.js | 2 +- package.json | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/config/jsdoc/api/template/static/scripts/main.js b/config/jsdoc/api/template/static/scripts/main.js index 1d904d48ac..acf43fde7b 100644 --- a/config/jsdoc/api/template/static/scripts/main.js +++ b/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 = '' + textParts[0] + ', ' + '' + diff --git a/package.json b/package.json index b1512c6bca..46b2cefc05 100644 --- a/package.json +++ b/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": {