Merge pull request #8862 from ahocevar/legacy-build

Legacy build and apidoc improvements

config/jsdoc/api/conf.json

@@ -15,16 +15,15 @@
   },
   "plugins": [
     "config/jsdoc/api/plugins/markdown",
-    "config/jsdoc/api/plugins/convert-types",
+    "jsdoc-plugin-typescript",
-    "config/jsdoc/api/plugins/normalize-longnames",
     "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": {
+  "typescript": {
-    "parser": "gfm"
+    "moduleRoot": "src"
   },
   "templates": {
     "cleverLinks": true,

config/jsdoc/api/index.md

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

config/jsdoc/api/plugins/api.js

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

config/jsdoc/api/plugins/convert-types.js

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

config/jsdoc/api/plugins/normalize-longnames.js

@@ -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('.', '~'));
-    }
-  }
-
-};

config/jsdoc/api/plugins/observable.js

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

config/jsdoc/api/template/tmpl/method.tmpl

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

config/jsdoc/api/template/tmpl/observables.tmpl

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

config/jsdoc/info/conf.json

@@ -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"
+    }
 }

config/rollup.js

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

config/webpack-config-legacy-build.js

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

package.json

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

src/ol/CollectionEventType.js

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

src/ol/ObjectEventType.js

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

src/ol/source/TileEventType.js

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

src/ol/source/Vector.js

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

src/ol/source/VectorEventType.js

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

tasks/generate-index.js

@@ -13,44 +13,41 @@ async function getSymbols() {
 }
 
 /**
- * Generate a list of imports.
+ * Generate an import statement.
- * @param {Array<Object>} symbols List of symbols.
+ * @param {Object} symbol Symbol.
- * @return {Promise<Array>} A list of imports sorted by export name.
+ * @param {string} member Member.
+ * @return {string} An import statement.
  */
-function getImports(symbols) {
+function getImport(symbol, member) {
-  const imports = {};
+  const defaultExport = symbol.name.split('~');
-  symbols.forEach(symbol => {
+  const namedExport = symbol.name.split('.');
-    const defaultExport = symbol.name.split('~');
+  if (defaultExport.length > 1) {
-    const namedExport = symbol.name.split('.');
+    const from = defaultExport[0].replace(/^module\:/, './');
-    if (defaultExport.length > 1) {
+    const importName = from.replace(/[.\/]+/g, '$');
-      const from = defaultExport[0].replace(/^module\:/, './');
+    return `import ${importName} from '${from}';`;
-      const importName = from.replace(/[.\/]+/g, '$');
+  } else if (namedExport.length > 1 && member) {
-      const defaultImport = `import ${importName} from '${from}';`;
+    const from = namedExport[0].replace(/^module\:/, './');
-      imports[defaultImport] = true;
+    const importName = from.replace(/[.\/]+/g, '_');
-    } else if (namedExport.length > 1) {
+    return `import {${member} as ${importName}$${member}} from '${from}';`;
-      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();
 }
 
 
 /**
  * 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 = Object.keys(imports).concat('\nvar ol = {};\n', nsdefs.sort()).concat(blocks.sort());
-  blocks.push('');
+  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);
-  return generateExports(symbols, {}, imports);
 }