Add typedef for TileArcGISRest source options

This was removed in 8b23a44f8f (inadvertently I think).
2018-04-19 17:58:39 -06:00
parent a09f7fb3bb
commit 5f8a5b3502
3 changed files with 42 additions and 228 deletions
@@ -10,6 +10,47 @@ import TileImage from '../source/TileImage.js';
 import {hash as tileCoordHash} from '../tilecoord.js';
 import {appendParams} from '../uri.js';
 /**
 * @typedef {Object} Options
 * @property {ol.AttributionLike} [attributions] Attributions.
 * @property {number} [cacheSize=2048] Cache size.
 * @property {null|string} [crossOrigin] The `crossOrigin` attribute for loaded images.
 * Note that you must provide a `crossOrigin` value if you are using the WebGL renderer
 * or if you want to access pixel data with the Canvas renderer.  See
 * {@link https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image}
 * for more detail.
 * @property {Object.<string,*>} [params] ArcGIS Rest parameters. This field is optional. Service defaults will be
 * used for any fields not specified. `FORMAT` is `PNG32` by default. `F` is `IMAGE` by
 * default. `TRANSPARENT` is `true` by default.  `BBOX, `SIZE`, `BBOXSR`,
 * and `IMAGESR` will be set dynamically. Set `LAYERS` to
 * override the default service layer visibility. See
 * {@link http://resources.arcgis.com/en/help/arcgis-rest-api/index.html#/Export_Map/02r3000000v7000000/}
 * for further reference.
 * @property {ol.tilegrid.TileGrid} [tileGrid] Tile grid. Base this on the resolutions,
 * tilesize and extent supported by the server.
 * If this is not defined, a default grid will be used: if there is a projection
 * extent, the grid will be based on that; if not, a grid based on a global
 * extent with origin at 0,0 will be used.
 * @property {ol.ProjectionLike} projection Projection.
 * @property {number} [reprojectionErrorThreshold=0.5] Maximum allowed reprojection error (in pixels).
 * Higher values can increase reprojection performance, but decrease precision.
 * @property {ol.TileLoadFunctionType} [tileLoadFunction] Optional function to load a tile given a URL.
 * The default is
 * ```js
 * function(imageTile, src) {
 *   imageTile.getImage().src = src;
 * };
 * ```
 * @property {string} [url] ArcGIS Rest service URL for a Map Service or Image Service. The
 * url should include /MapServer or /ImageServer.
 * @property {boolean} [wrapX=true] Whether to wrap the world horizontally.
 * @property {number} [transition] Duration of the opacity transition for rendering.  To disable the opacity
 * transition, pass `transition: 0`.
 * @property {Array.<string>} urls ArcGIS Rest service urls. Use this instead of `url` when the ArcGIS
 * Service supports multiple urls for export requests.
 */
 /**
 * @classdesc
 * Layer source for tile data from ArcGIS Rest services. Map and Image
@@ -20,8 +61,7 @@ import {appendParams} from '../uri.js';
 *
 * @constructor
 * @extends {module:ol/source/TileImage~TileImage}
- * @param {olx.source.TileArcGISRestOptions=} opt_options Tile ArcGIS Rest
+ * @param {module:ol/source/TileArcGISRest~Options=} opt_options Tile ArcGIS Rest options.
 *     options.
 * @api
 */
 const TileArcGISRest = function(opt_options) {
@@ -1,39 +0,0 @@
 /**
 * @namespace olx
 */
 /**
 * @namespace olx.control
 */
 /**
 * @namespace olx.format
 */
 /**
 * @namespace olx.interaction
 */
 /**
 * @namespace olx.layer
 */
 /**
 * @namespace olx.parser
 */
 /**
 * @namespace olx.render
 */
 /**
 * @namespace olx.source
 */
 /**
 * @namespace olx.style
 */
 /**
 * @namespace olx.tilegrid
 */
@@ -1,187 +0,0 @@
 const fs = require('fs');
 const util = require('util');
 const path = require('path');
 const readFile = util.promisify(fs.readFile);
 const writeFile = util.promisify(fs.writeFile);
 const externs = path.resolve(__dirname, '../externs');
 function parse(source) {
  const length = source.length;
  let index = 0;
  const IN_CODE = 'in code';
  const IN_COMMENT = 'in comment';
  function next() {
    const char = source.charAt(index);
    ++index;
    return char;
  }
  function scanLine() {
    let char = next();
    let line = '';
    while (index < length && char !== '\n') {
      line += char;
      char = next();
    }
    return line;
  }
  let state = IN_CODE;
  const blocks = [];
  let comment;
  while (index < length) {
    const line = scanLine();
    if (state === IN_CODE) {
      if (line === '/**') {
        state = IN_COMMENT;
        comment = '';
      }
      continue;
    }
    // in a comment
    if (!line) {
      continue;
    }
    if (line !== ' */') {
      comment += line + '\n';
      continue;
    }
    // comment is done
    const code = scanLine();
    if (code.startsWith('olx')) {
      blocks.push({code, comment});
    }
    state = IN_CODE;
  }
  return blocks;
 }
 function processParam(name, comment) {
  const IN_DESCRIPTION = 'in description';
  const IN_TYPE = 'in type';
  const DONE = 'done';
  const lines = comment.split('\n');
  lines.pop(); // ends with newline
  let description = '';
  let type;
  let state = IN_DESCRIPTION;
  lines.forEach(line => {
    if (state === DONE) {
      throw new Error(`Extra comment after @api for param ${name}:\n${comment}`);
    }
    if (!(line.startsWith(' * ') || line === ' *')) {
      throw new Error(`Unexpected comment start for param ${name}:\n${comment}`);
    }
    if (line.indexOf('@type ') === 3) {
      state = IN_TYPE;
      if (type) {
        throw new Error(`Duplicate type for param ${name}:\n${comment}`);
      }
      type = line.slice(9);
      return;
    }
    if (line.indexOf('@api') === 3) {
      state = DONE;
      return;
    }
    if (state === IN_DESCRIPTION) {
      if (type) {
        throw new Error(`Description after type for param ${name}:\n${comment}`);
      }
      description += line.slice(3) + '\n';
      return;
    }
    type += line.slice(3) + '\n';
  });
  return {name, type, description};
 }
 function getName(name) {
  if (!name.startsWith('olx.')) {
    throw new Error(`Unexpected name: ${name}`);
  }
  return name.slice(4).replace(/\./g, '_');
 }
 function processBlock(block, data) {
  const name = getName(block.code.slice(0, -1));
  const protoStart = name.indexOf('_prototype_');
  if (protoStart > 0) {
    const parentName = name.slice(0, protoStart);
    const childName = name.slice(protoStart + 11);
    if (!(parentName in data)) {
      throw new Error(`No parent for ${block.code}`);
    }
    const param = processParam(childName, block.comment);
    data[parentName].params.push(param);
    return;
  }
  if (block.comment.indexOf('@typedef') === -1) {
    if (block.comment.indexOf('Namespace.') === -1) {
      throw new Error(`Unexpected comment for ${block.code}`);
    }
    return;
  }
  data[name] = {
    name,
    comment: block.comment,
    params: []
  };
 }
 function processBlocks(blocks) {
  const data = {};
  blocks.forEach(block => processBlock(block, data));
  return data;
 }
 function format(data) {
  let source = '';
  for (const name in data) {
    // add the @typedef
    source += `\n/**\n * @typedef {Object} ${name}\n`;
    const params = data[name].params;
    if (!params.length) {
      throw new Error(`No params for ${name}`);
    }
    params.forEach(param => {
      const description = param.description.replace(/\n$/, '').split('\n').join('\n * ');
      source += ` * @property ${param.type} ${param.name} ${description}\n`;
    });
    source += ' */\n\n';
  }
  return source;
 }
 async function main() {
  const source = String(await readFile(path.join(externs, 'olx.js')));
  const blocks = parse(source);
  const data = processBlocks(blocks);
  const output = format(data);
  await writeFile(path.join(externs, 'xol.js'), output);
 }
 if (require.main === module) {
  main().catch(err => {
    process.stdout.write(`${err.stack}\n`, () => process.exit(1));
  });
 }