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

Merge pull request #8862 from ahocevar/legacy-build

Browse Source 
Legacy build and apidoc improvements
This commit is contained in:
Andreas Hocevar
2018-10-31 08:35:38 +01:00
committed by GitHub
parent 6f57a272d0 f8c0d284de
commit c90b8c2a12
18 changed files with 74 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
config/jsdoc/api/conf.json
View File

@@ -15,16 +15,15 @@
},
"plugins": [
"config/jsdoc/api/plugins/markdown",
"config/jsdoc/api/plugins/convert-types",
"config/jsdoc/api/plugins/normalize-longnames",
"jsdoc-plugin-typescript",
"config/jsdoc/api/plugins/inline-options",
"config/jsdoc/api/plugins/inheritdoc",
"config/jsdoc/api/plugins/events",
"config/jsdoc/api/plugins/observable",
"config/jsdoc/api/plugins/api"
],
"markdown": {
"parser": "gfm"
"typescript": {
"moduleRoot": "src"
},
"templates": {
"cleverLinks": true,

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

@@ -34,7 +34,7 @@ Interactions for [vector features](module-ol_Feature-Feature.html)
<tr><th>Projections</th><th>Observable objects</th><th>Other components</th></tr>
<tr><td><p>All coordinates and extents need to be provided in view projection (default: EPSG:3857). To transform, use [ol/proj#transform()](module-ol_proj.html#.transform) and [ol/proj#transformExtent()](module-ol_proj.html#.transformExtent).</p>
[ol/proj](module-ol_proj.html)</td>
<td><p>Changes to all [ol/Object](module-ol_Object-BaseObject.html)s can be observed by calling the [object.on('propertychange')](module-ol_Object-BaseObject.html#on) method. Listeners receive an [ol/Object~ObjectEvent](module-ol_Object-ObjectEvent.html) with information on the changed property and old value.</p>
<td><p>Changes to all [ol/Object](module-ol_Object-BaseObject.html)s can be observed by calling the [object.on('propertychange')](module-ol_Object-BaseObject.html#on) method. Listeners receive an [ol/Object.ObjectEvent](module-ol_Object-ObjectEvent.html) with information on the changed property and old value.</p>
<td>
[ol/Geolocation](module-ol_Geolocation.html)<br>
[ol/Overlay](module-ol_Overlay-Overlay.html)<br></td>

2
config/jsdoc/api/plugins/api.js
View File

@@ -102,6 +102,8 @@ exports.handlers = {
modules[doclet.longname.split(/[~\.]/).shift()] = true;
if (!(doclet.longname in classes)) {
classes[doclet.longname] = doclet;
} else if ('augments' in doclet) {
classes[doclet.longname].augments = doclet.augments;
}
}
if (doclet.name === doclet.longname && !doclet.memberof) {

139
config/jsdoc/api/plugins/convert-types.js
View File

@@ -1,139 +0,0 @@
const path = require('path');
const fs = require('fs');
const importRegEx = /(typeof )?import\("([^"]*)"\)\.([^ \.\|\}><,\)=\n]*)([ \.\|\}><,\)=\n])/g;
const typedefRegEx = /@typedef \{[^\}]*\} ([^ \r?\n?]*)/;
const defaultExports = {};
const fileNodes = {};
function getDefaultExportName(moduleId, parser) {
if (!defaultExports[moduleId]) {
if (!fileNodes[moduleId]) {
const classDeclarations = {};
const absolutePath = path.join(process.cwd(), 'src', moduleId + '.js');
const file = fs.readFileSync(absolutePath, 'UTF-8');
const node = fileNodes[moduleId] = parser.astBuilder.build(file, absolutePath);
if (node.program && node.program.body) {
const nodes = node.program.body;
for (let i = 0, ii = nodes.length; i < ii; ++i) {
const node = nodes[i];
if (node.type === 'ClassDeclaration') {
classDeclarations[node.id.name] = node;
} else if (node.type === 'ExportDefaultDeclaration') {
const classDeclaration = classDeclarations[node.declaration.name];
if (classDeclaration) {
defaultExports[moduleId] = classDeclaration.id.name;
}
}
}
}
}
}
if (!defaultExports[moduleId]) {
defaultExports[moduleId] = '';
}
return defaultExports[moduleId];
}
exports.astNodeVisitor = {
visitNode: function(node, e, parser, currentSourceName) {
if (node.type === 'File') {
const modulePath = path.relative(path.join(process.cwd(), 'src'), currentSourceName).replace(/\.js$/, '');
fileNodes[modulePath] = node;
const identifiers = {};
if (node.program && node.program.body) {
const nodes = node.program.body;
for (let i = 0, ii = nodes.length; i < ii; ++i) {
let node = nodes[i];
if (node.type === 'ExportNamedDeclaration' && node.declaration) {
node = node.declaration;
}
if (node.type === 'ImportDeclaration') {
node.specifiers.forEach(specifier => {
let defaultImport = false;
switch (specifier.type) {
case 'ImportDefaultSpecifier':
defaultImport = true;
// fallthrough
case 'ImportSpecifier':
identifiers[specifier.local.name] = {
defaultImport,
value: node.source.value
};
break;
default:
}
});
} else if (node.type === 'ClassDeclaration') {
if (node.id && node.id.name) {
identifiers[node.id.name] = {
value: path.basename(currentSourceName)
};
}
// Add class inheritance information because JSDoc does not honor
// the ES6 class's `extends` keyword
if (node.superClass && node.leadingComments) {
const leadingComment = node.leadingComments[node.leadingComments.length - 1];
const lines = leadingComment.value.split(/\r?\n/);
lines.push(lines[lines.length - 1]);
const identifier = identifiers[node.superClass.name];
if (identifier) {
const absolutePath = path.resolve(path.dirname(currentSourceName), identifier.value);
const moduleId = path.relative(path.join(process.cwd(), 'src'), absolutePath).replace(/\.js$/, '');
const exportName = identifier.defaultImport ? getDefaultExportName(moduleId, parser) : node.superClass.name;
lines[lines.length - 2] = ' * @extends ' + `module:${moduleId}${exportName ? '~' + exportName : ''}`;
} else {
lines[lines.length - 2] = ' * @extends ' + node.superClass.name;
}
leadingComment.value = lines.join('\n');
}
}
}
}
if (node.comments) {
node.comments.forEach(comment => {
//TODO Handle typeof, to indicate that a constructor instead of an
// instance is needed.
comment.value = comment.value.replace(/typeof /g, '');
// Convert `import("path/to/module").export` to
// `module:path/to/module~Name`
let importMatch;
while ((importMatch = importRegEx.exec(comment.value))) {
importRegEx.lastIndex = 0;
const rel = path.resolve(path.dirname(currentSourceName), importMatch[2]);
const importModule = path.relative(path.join(process.cwd(), 'src'), rel).replace(/\.js$/, '');
const exportName = importMatch[3] === 'default' ? getDefaultExportName(importModule, parser) : importMatch[3];
const replacement = `module:${importModule}${exportName ? '~' + exportName : ''}`;
comment.value = comment.value.replace(importMatch[0], replacement + importMatch[4]);
}
// Treat `@typedef`s like named exports
const typedefMatch = comment.value.replace(/\r?\n?\s*\*\s/g, ' ').match(typedefRegEx);
if (typedefMatch) {
identifiers[typedefMatch[1]] = {
value: path.basename(currentSourceName)
};
}
// Replace local types with the full `module:` path
Object.keys(identifiers).forEach(key => {
const regex = new RegExp(`(@fires |[\{<\|,] ?)${key}`, 'g');
if (regex.test(comment.value)) {
const identifier = identifiers[key];
const absolutePath = path.resolve(path.dirname(currentSourceName), identifier.value);
const moduleId = path.relative(path.join(process.cwd(), 'src'), absolutePath).replace(/\.js$/, '');
const exportName = identifier.defaultImport ? getDefaultExportName(moduleId, parser) : key;
comment.value = comment.value.replace(regex, '$1' + `module:${moduleId}${exportName ? '~' + exportName : ''}`);
}
});
});
}
}
}
};

21
config/jsdoc/api/plugins/normalize-longnames.js
View File

@@ -1,21 +0,0 @@
/**
* @filedesc
* Normalize module path to make no distinction between static and member at
* the module level.
*/
exports.handlers = {
/**
* Adds default export to module path types without name
* @param {Object} e Event object.
*/
newDoclet: function(e) {
const doclet = e.doclet;
const module = doclet.longname.split('#').shift();
if (module.indexOf('module:') == 0 && module.indexOf('.') !== -1) {
doclet.longname = doclet.longname.replace(module, module.replace('.', '~'));
}
}
};

2
config/jsdoc/api/plugins/observable.js
View File

@@ -47,7 +47,7 @@ exports.handlers = {
if (!cls.fires) {
cls.fires = [];
}
event = 'module:ol/Object~ObjectEvent#event:change:' + name;
event = 'module:ol/Object.ObjectEvent#event:change:' + name;
if (cls.fires.indexOf(event) == -1) {
cls.fires.push(event);
}

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

@@ -77,7 +77,7 @@ var self = this;
(<?js= self.linkto(eventClass.longname) ?>)
<?js } ?>
<?js } ?>
<?js= self.partial('stability.tmpl', eventDoclet || (data.stability ? data : {stability: 'experimental'})) ?>
<?js= self.partial('stability.tmpl', eventDoclet || (data.stability ? data : {})) ?>
<?js if (description) { ?> -
<?js= description ?>
<?js } ?>

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">ol/Object.ObjectEvent</a> type</th>
<th class="last">Description</th>
</tr>
</thead>

6
config/jsdoc/info/conf.json
View File

@@ -10,8 +10,12 @@
"includePattern": "\\.js$"
},
"plugins": [
"jsdoc-plugin-typescript",
"config/jsdoc/info/api-plugin",
"config/jsdoc/info/define-plugin",
"config/jsdoc/info/virtual-plugin"
]
],
"typescript": {
"moduleRoot": "src"
}
}

21
config/rollup.js
View File

@@ -1,21 +0,0 @@
// Rollup configuration for the full build
import noderesolve from 'rollup-plugin-node-resolve';
import commonjs from 'rollup-plugin-commonjs';
import {uglify} from 'rollup-plugin-uglify';
import buble from 'rollup-plugin-buble';
import sourcemaps from 'rollup-plugin-sourcemaps';
export default {
input: 'build/index.js',
output: [
{file: 'build/ol.js', format: 'iife', sourcemap: true}
],
plugins: [
noderesolve(),
commonjs(),
buble(),
uglify(),
sourcemaps()
]
};

13
config/webpack-config-legacy-build.js Normal file
View File

@@ -0,0 +1,13 @@
const path = require('path');
module.exports = {
entry: './build/index.js',
devtool: 'source-map',
mode: 'production',
output: {
path: path.resolve('./build/legacy'),
filename: 'ol.js',
library: 'ol',
libraryTarget: 'umd',
libraryExport: 'default'
}
};

8
package.json
View File

@@ -18,7 +18,7 @@
"build-examples": "webpack --config examples/webpack/config.js --mode production",
"build-package": "npm run transpile && npm run copy-css && node tasks/prepare-package && cp README.md build/ol",
"build-index": "npm run build-package && node tasks/generate-index",
"build-legacy": "rm -rf build && npm run build-index && rollup --config config/rollup.js && cleancss --source-map src/ol/ol.css -o build/ol.css",
"build-legacy": "rm -rf build && npm run build-index && webpack --config config/webpack-config-legacy-build.js && cleancss --source-map src/ol/ol.css -o build/legacy/ol.css",
"copy-css": "cp src/ol/ol.css build/ol/ol.css",
"transpile": "rm -rf build/ol && mkdir -p build && buble --input src/ol --output build/ol --no modules --sourcemap",
"typecheck": "tsc --pretty",
@@ -60,6 +60,7 @@
"istanbul": "0.4.5",
"jquery": "3.3.1",
"jsdoc": "3.5.5",
"jsdoc-plugin-typescript": "^1.0.2",
"karma": "^3.0.0",
"karma-chrome-launcher": "2.2.0",
"karma-coverage": "^1.1.1",
@@ -74,11 +75,6 @@
"pixelmatch": "^4.0.2",
"proj4": "2.5.0",
"rollup": "0.66.6",
"rollup-plugin-buble": "0.19.4",
"rollup-plugin-commonjs": "9.2.0",
"rollup-plugin-node-resolve": "3.4.0",
"rollup-plugin-sourcemaps": "0.4.2",
"rollup-plugin-uglify": "6.0.0",
"sinon": "^6.0.0",
"typescript": "^3.1.0-dev.20180905",
"uglifyjs-webpack-plugin": "^2.0.1",

4
src/ol/CollectionEventType.js
View File

@@ -8,13 +8,13 @@
export default {
/**
* Triggered when an item is added to the collection.
* @event module:ol/Collection~CollectionEvent#add
* @event module:ol/Collection.CollectionEvent#add
* @api
*/
ADD: 'add',
/**
* Triggered when an item is removed from the collection.
* @event module:ol/Collection~CollectionEvent#remove
* @event module:ol/Collection.CollectionEvent#remove
* @api
*/
REMOVE: 'remove'

2
src/ol/ObjectEventType.js
View File

@@ -8,7 +8,7 @@
export default {
/**
* Triggered when a property is changed.
* @event module:ol/Object~ObjectEvent#propertychange
* @event module:ol/Object.ObjectEvent#propertychange
* @api
*/
PROPERTYCHANGE: 'propertychange'

6
src/ol/source/TileEventType.js
View File

@@ -9,7 +9,7 @@ export default {
/**
* Triggered when a tile starts loading.
* @event module:ol/source/Tile~TileSourceEvent#tileloadstart
* @event module:ol/source/Tile.TileSourceEvent#tileloadstart
* @api
*/
TILELOADSTART: 'tileloadstart',
@@ -17,14 +17,14 @@ export default {
/**
* Triggered when a tile finishes loading, either when its data is loaded,
* or when loading was aborted because the tile is no longer needed.
* @event module:ol/source/Tile~TileSourceEvent#tileloadend
* @event module:ol/source/Tile.TileSourceEvent#tileloadend
* @api
*/
TILELOADEND: 'tileloadend',
/**
* Triggered if tile loading results in an error.
* @event module:ol/source/Tile~TileSourceEvent#tileloaderror
* @event module:ol/source/Tile.TileSourceEvent#tileloaderror
* @api
*/
TILELOADERROR: 'tileloaderror'

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

@@ -154,7 +154,7 @@ export class VectorSourceEvent extends Event {
* by this source are suitable for editing. See {@link module:ol/source/VectorTile~VectorTile} for
* vector data that is optimized for rendering.
*
* @fires ol/source/Vector~VectorSourceEvent
* @fires ol/source/Vector.VectorSourceEvent
* @api
*/
class VectorSource extends Source {
@@ -469,7 +469,7 @@ class VectorSource extends Source {
/**
* Remove all features from the source.
* @param {boolean=} opt_fast Skip dispatching of {@link module:ol/source/Vector~VectorSourceEvent#removefeature} events.
* @param {boolean=} opt_fast Skip dispatching of {@link module:ol/source/Vector.VectorSourceEvent#removefeature} events.
* @api
*/
clear(opt_fast) {

8
src/ol/source/VectorEventType.js
View File

@@ -8,21 +8,21 @@
export default {
/**
* Triggered when a feature is added to the source.
* @event ol/source/Vector~VectorSourceEvent#addfeature
* @event ol/source/Vector.VectorSourceEvent#addfeature
* @api
*/
ADDFEATURE: 'addfeature',
/**
* Triggered when a feature is updated.
* @event ol/source/Vector~VectorSourceEvent#changefeature
* @event ol/source/Vector.VectorSourceEvent#changefeature
* @api
*/
CHANGEFEATURE: 'changefeature',
/**
* Triggered when the clear method is called on the source.
* @event ol/source/Vector~VectorSourceEvent#clear
* @event ol/source/Vector.VectorSourceEvent#clear
* @api
*/
CLEAR: 'clear',
@@ -30,7 +30,7 @@ export default {
/**
* Triggered when a feature is removed from the source.
* See {@link module:ol/source/Vector#clear source.clear()} for exceptions.
* @event ol/source/Vector~VectorSourceEvent#removefeature
* @event ol/source/Vector.VectorSourceEvent#removefeature
* @api
*/
REMOVEFEATURE: 'removefeature'

63
tasks/generate-index.js
View File

@@ -13,44 +13,41 @@ async function getSymbols() {
}
/**
* Generate a list of imports.
* @param {Array<Object>} symbols List of symbols.
* @return {Promise<Array>} A list of imports sorted by export name.
* Generate an import statement.
* @param {Object} symbol Symbol.
* @param {string} member Member.
* @return {string} An import statement.
*/
function getImports(symbols) {
const imports = {};
symbols.forEach(symbol => {
const defaultExport = symbol.name.split('~');
const namedExport = symbol.name.split('.');
if (defaultExport.length > 1) {
const from = defaultExport[0].replace(/^module\:/, './');
const importName = from.replace(/[.\/]+/g, '$');
const defaultImport = `import ${importName} from '${from}';`;
imports[defaultImport] = true;
} else if (namedExport.length > 1) {
const from = namedExport[0].replace(/^module\:/, './');
const importName = from.replace(/[.\/]+/g, '_');
const namedImport = `import * as ${importName} from '${from}';`;
imports[namedImport] = true;
}
});
return Object.keys(imports).sort();
function getImport(symbol, member) {
const defaultExport = symbol.name.split('~');
const namedExport = symbol.name.split('.');
if (defaultExport.length > 1) {
const from = defaultExport[0].replace(/^module\:/, './');
const importName = from.replace(/[.\/]+/g, '$');
return `import ${importName} from '${from}';`;
} else if (namedExport.length > 1 && member) {
const from = namedExport[0].replace(/^module\:/, './');
const importName = from.replace(/[.\/]+/g, '_');
return `import {${member} as ${importName}$${member}} from '${from}';`;
}
}
/**
* Generate code to export a named symbol.
* @param {string} name Symbol name.
* @param {Object} symbol Symbol.
* @param {Object<string, string>} namespaces Already defined namespaces.
* @param {Object} imports Imports.
* @return {string} Export code.
*/
function formatSymbolExport(name, namespaces) {
function formatSymbolExport(symbol, namespaces, imports) {
const name = symbol.name;
const parts = name.split('~');
const isNamed = parts[0].indexOf('.') !== -1;
const nsParts = parts[0].replace(/^module\:/, '').split(/[\/\.]/);
const last = nsParts.length - 1;
const importName = isNamed ?
'_' + nsParts.slice(0, last).join('_') + '.' + nsParts[last] :
'_' + nsParts.slice(0, last).join('_') + '$' + nsParts[last] :
'$' + nsParts.join('$');
let line = nsParts[0];
for (let i = 1, ii = nsParts.length; i < ii; ++i) {
@@ -58,6 +55,7 @@ function formatSymbolExport(name, namespaces) {
namespaces[line] = (line in namespaces ? namespaces[line] : true) && i < ii - 1;
}
line += ` = ${importName};`;
imports[getImport(symbol, nsParts.pop())] = true;
return line;
}
@@ -69,12 +67,18 @@ function formatSymbolExport(name, namespaces) {
* @param {Array<string>} imports List of all imports.
* @return {string} Export code.
*/
function generateExports(symbols, namespaces, imports) {
function generateExports(symbols) {
const namespaces = {};
const imports = [];
let blocks = [];
symbols.forEach(function(symbol) {
const name = symbol.name;
if (name.indexOf('#') == -1) {
const block = formatSymbolExport(name, namespaces);
const imp = getImport(symbol);
if (imp) {
imports[getImport(symbol)] = true;
}
const block = formatSymbolExport(symbol, namespaces, imports);
if (block !== blocks[blocks.length - 1]) {
blocks.push(block);
}
@@ -87,8 +91,8 @@ function generateExports(symbols, namespaces, imports) {
nsdefs.push(`${ns[i]} = {};`);
}
}
blocks = imports.concat('\nvar ol = window[\'ol\'] = {};\n', nsdefs.sort()).concat(blocks.sort());
blocks.push('');
blocks = Object.keys(imports).concat('\nvar ol = {};\n', nsdefs.sort()).concat(blocks.sort());
blocks.push('', 'export default ol;');
return blocks.join('\n');
}
@@ -99,8 +103,7 @@ function generateExports(symbols, namespaces, imports) {
*/
async function main() {
const symbols = await getSymbols();
const imports = await getImports(symbols);
return generateExports(symbols, {}, imports);
return generateExports(symbols);
}