Merge pull request #1979 from tschaub/custom-build

Annotation for exportable methods.  Node based tasks for generating exports and a custom build.

Fixes #613.

apidoc/conf.json

@@ -14,16 +14,19 @@
         ],
         "include": [
             "src",
+            "externs/oli.js",
             "externs/olx.js"
         ]
     },
     "plugins": [
         "node_modules/jsdoc/plugins/markdown",
         "apidoc/plugins/inheritdoc",
-        "apidoc/plugins/exports",
+        "apidoc/plugins/interface",
+        "apidoc/plugins/typedefs",
+        "apidoc/plugins/inheritdoc",
+        "apidoc/plugins/api",
         "apidoc/plugins/todo",
-        "apidoc/plugins/observable",
-        "apidoc/plugins/stability"
+        "apidoc/plugins/observable"
     ],
     "markdown": {
         "parser": "gfm"

apidoc/plugins/api.js

@@ -0,0 +1,77 @@
+/**
+ * Define an @api tag
+ */
+var conf = env.conf.stability;
+var defaultLevels = ["deprecated","experimental","unstable","stable","frozen","locked"];
+var levels = conf.levels || defaultLevels;
+var util = require('util');
+exports.defineTags = function(dictionary) {
+  dictionary.defineTag('api', {
+    mustHaveValue: false,
+    canHaveType: false,
+    canHaveName: false,
+    onTagged: function(doclet, tag) {
+      var level = tag.text || "experimental";
+      if (levels.indexOf(level) >= 0) {
+        doclet.stability = level;
+      } else {
+        var errorText = util.format('Invalid stability level (%s) in %s line %s', tag.text, doclet.meta.filename, doclet.meta.lineno);
+        require('jsdoc/util/error').handle( new Error(errorText) );
+      }
+    }
+  });
+};
+
+
+
+/*
+ * Based on @stability annotations, and assuming that items with no @stability
+ * annotation should not be documented, this plugin removes undocumented symbols
+ * from the documentation. Undocumented classes with documented members get a
+ * 'hideConstructur' property, which is read by the template so it can hide the
+ * constructor.
+ */
+
+function hasApiMembers(doclet) {
+  return doclet.longname.split('#')[0] == this.longname;
+}
+
+var api = [];
+
+exports.handlers = {
+
+  newDoclet: function(e) {
+    var doclet = e.doclet;
+    // Keep track of api items - needed in parseComplete to determine classes
+    // with api members.
+    if (doclet.stability) {
+      api.push(doclet);
+    }
+    // Mark explicity defined namespaces - needed in parseComplete to keep
+    // namespaces that we need as containers for api items.
+    if (/.*\.jsdoc$/.test(doclet.meta.filename) && doclet.kind == 'namespace') {
+      doclet.namespace_ = true;
+    }
+  },
+
+  parseComplete: function(e) {
+    var doclets = e.doclets;
+    for (var i = doclets.length - 1; i >= 0; --i) {
+      var doclet = doclets[i];
+      // Always document namespaces and items with stability annotation
+      if (doclet.stability || doclet.namespace_) {
+        continue;
+      }
+      if (doclet.kind == 'class' && api.some(hasApiMembers, doclet)) {
+        // Mark undocumented classes with documented members as unexported.
+        // This is used in ../template/tmpl/container.tmpl to hide the
+        // constructor from the docs.
+        doclet.hideConstructor = true;
+      } else {
+        // Remove all other undocumented symbols
+        doclets.splice(i, 1);
+      }
+    }
+  }
+
+};

apidoc/plugins/exports.js

@@ -1,120 +0,0 @@
-/*
- * This plugin parses externs/oli.js as well as goog.exportSymbol and
- * goog.exportProperty calls to build a list of API symbols and properties.
- * Unexported modules linked from @param or @fires will be marked unexported,
- * and the documentation will not contain the constructor. Everything else is
- * marked undocumented, which will remove it from the docs.
- */
-
-var api = [];
-var unexported = [];
-
-function collectExports(source) {
-  var i, ii, symbol, property;
-  var syms = source.match(/goog\.exportSymbol\([^\)]*\)/g);
-  if (syms) {
-    i = 0; ii = syms.length;
-    for (; i < ii; ++i) {
-      symbol = syms[i].match(/'([^']*)'/)[1];
-      api.push(symbol);
-    }
-  }
-  var props = source.match(/goog\.exportProperty\([^\)]*\)/g);
-  if (props) {
-    i = 0; ii = props.length;
-    for (; i < ii; ++i) {
-      property = props[i].match(/[^,]*,[^,]*,\r?\n? *([^\)]*)\)/)[1]
-          .replace('.prototype.', '#');
-      api.push(property);
-    }
-  }
-}
-
-function collectOliExports(source) {
-  var oli = source.match(/[^\{]oli\.([^;^ ]*);? ?/g);
-  if (oli) {
-    i = 0; ii = oli.length;
-    for (; i < ii; ++i) {
-      property = 'ol.' + oli[i].match(/oli.([^;]*)/)[1]
-          .replace('.prototype.', '#');
-      unexported.push(property);
-    }
-  }
-}
-
-var encoding = env.conf.encoding || 'utf8';
-var fs = require('jsdoc/fs');
-collectExports(fs.readFileSync('build/src/external/src/exports.js', encoding));
-collectOliExports(fs.readFileSync('externs/oli.js', encoding));
-
-
-exports.handlers = {
-  
-  beforeParse: function(e) {
-    if (/\.js$/.test(e.filename)) {
-      collectExports(e.source);
-    }
-  },
-  
-  newDoclet: function(e) {
-    var i, ii, j, jj;
-    if (e.doclet.meta.filename == "olx.js" && e.doclet.longname != 'olx') {
-      api.push(e.doclet.longname);
-    }
-    if (api.indexOf(e.doclet.longname) > -1) {
-      var names, name;
-      var params = e.doclet.params;
-      if (params) {
-        for (i = 0, ii = params.length; i < ii; ++i) {
-          names = params[i].type.names;
-          if (names) {
-            for (j = 0, jj=names.length; j < jj; ++j) {
-              name = names[j];
-              if (unexported.indexOf(name) === -1) {
-                unexported.push(name);
-              }
-            }
-          }
-        }
-      }
-      var links = e.doclet.comment.match(/\{@link ([^\}]*)\}/g);
-      if (links) {
-        for (i=0, ii=links.length; i < ii; ++i) {
-          var link = links[i].match(/\{@link (.*)\}/)[1];
-          if (unexported.indexOf(link) === -1) {
-            unexported.push(link);
-          }
-        }
-      }
-    }
-  },
-  
-  parseComplete: function(e) {
-    for (var j = e.doclets.length - 1; j >= 0; --j) {
-      var doclet = e.doclets[j];
-      if (doclet.meta.filename == 'olx.js' && doclet.kind == 'typedef') {
-        for (var i = e.doclets.length - 1; i >= 0; --i) {
-          var propertyDoclet = e.doclets[i];
-          if (propertyDoclet.memberof == doclet.longname) {
-            if (!doclet.properties) {
-              doclet.properties = [];
-            }
-            doclet.properties.unshift(propertyDoclet);
-            e.doclets.splice(i, 1)
-          }
-        }
-      }
-      if (doclet.kind == 'namespace' || doclet.kind == 'event' || doclet.fires) {
-        continue;
-      }
-      var fqn = doclet.longname;
-      if (fqn) {
-        doclet.unexported = (api.indexOf(fqn) === -1 && unexported.indexOf(fqn) !== -1);
-        if (api.indexOf(fqn) === -1 && unexported.indexOf(fqn) === -1) {
-          e.doclets.splice(j, 1);
-        }
-      }
-    }
-  }
-
-};

apidoc/plugins/inheritdoc.js

@@ -5,11 +5,104 @@
  * TODO: Remove this hack when https://github.com/jsdoc3/jsdoc/issues/53
  * is addressed.
  */
-exports.astNodeVisitor = {
 
-  visitNode: function(node, e, parser, currentSourceName) {
-    if (/@(inheritDoc)(\n|\r)/.test(e.comment)) {
-      e.preventDefault = true;
+
+exports.defineTags = function(dictionary) {
+  dictionary.defineTag('inheritDoc', {
+    mustHaveValue: false,
+    canHaveType: false,
+    canHaveName: false,
+    onTagged: function(doclet, tag) {
+      doclet.inheritdoc = true;
+    }
+  });
+};
+
+
+var lookup = {};
+var incompleteByClass = {};
+var keepKeys = ['comment', 'meta', 'name', 'memberof', 'longname', 'augment',
+    'stability'];
+
+exports.handlers = {
+
+  newDoclet: function(e) {
+    var doclet = e.doclet;
+    var incompletes;
+    if (!(doclet.longname in lookup)) {
+      lookup[doclet.longname] = [];
+    }
+    lookup[doclet.longname].push(doclet);
+    if (doclet.inheritdoc) {
+      if (!(doclet.memberof in incompleteByClass)) {
+        incompleteByClass[doclet.memberof] = [];
+      }
+      incompletes = incompleteByClass[doclet.memberof];
+      if (incompletes.indexOf(doclet.name) == -1) {
+        incompletes.push(doclet.name);
+      }
+    }
+  },
+
+  parseComplete: function(e) {
+    var ancestors, candidate, candidates, doclet, i, j, k, l, key;
+    var incompleteDoclet, stability, incomplete, incompletes;
+    var doclets = e.doclets;
+    for (i = doclets.length - 1; i >= 0; --i) {
+      doclet = doclets[i];
+      if (doclet.augments) {
+        ancestors = [].concat(doclet.augments);
+      }
+      incompletes = incompleteByClass[doclet.longname];
+      if (ancestors && incompletes) {
+        // collect ancestors from the whole hierarchy
+        for (j = 0; j < ancestors.length; ++j) {
+          candidates = lookup[ancestors[j]];
+          if (candidates) {
+            for (k = candidates.length - 1; k >= 0; --k) {
+              candidate = candidates[k];
+              if (candidate.augments) {
+                ancestors = ancestors.concat(candidate.augments);
+              }
+            }
+          }
+        }
+        // walk through all inheritDoc members
+        for (j = incompletes.length - 1; j >= 0; --j) {
+          incomplete = incompletes[j];
+          candidates = lookup[doclet.longname + '#' + incomplete];
+          if (candidates) {
+            // get the incomplete doclet that needs to be augmented
+            for (k = candidates.length - 1; k >= 0; --k) {
+              incompleteDoclet = candidates[k];
+              if (incompleteDoclet.inheritdoc) {
+                break;
+              }
+            }
+          }
+          // find the documented ancestor
+          for (k = ancestors.length - 1; k >= 0; --k) {
+            candidates = lookup[ancestors[k] + '#' + incomplete];
+            if (candidates) {
+              for (l = candidates.length - 1; l >= 0; --l) {
+                candidate = candidates[l];
+                if (candidate && !candidate.inheritdoc) {
+                  stability = candidate.stability || incompleteDoclet.stability
+                  if (stability) {
+                    incompleteDoclet.stability = stability;
+                    for (key in candidate) {
+                      if (candidate.hasOwnProperty(key) &&
+                          keepKeys.indexOf(key) == -1) {
+                        incompleteDoclet[key] = candidate[key];
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
 

apidoc/plugins/interface.js

@@ -0,0 +1,26 @@
+var util = require('util');
+exports.defineTags = function(dictionary) {
+
+  var classTag = dictionary.lookUp('class');
+  dictionary.defineTag('interface', {
+    mustHaveValue: false,
+    onTagged: function(doclet, tag) {
+      classTag.onTagged.apply(this, arguments);
+      doclet.interface = true;
+    }
+  });
+
+  var augmentsTag = dictionary.lookUp('augments');
+  dictionary.defineTag('implements', {
+    mustHaveValue: true,
+    onTagged: function(doclet, tag) {
+      tag.value = tag.value.match(/^\{?([^\}]*)\}?$/)[1];
+      augmentsTag.onTagged.apply(this, arguments);
+      if (!doclet.implements) {
+        doclet.implements = [];
+      }
+      doclet.implements.push(tag.value);
+    }
+  });
+
+};

apidoc/plugins/stability.js

@@ -1,20 +0,0 @@
-var conf = env.conf.stability;
-var defaultLevels = ["deprecated","experimental","unstable","stable","frozen","locked"];
-var levels = conf.levels || defaultLevels;
-var util = require('util');
-exports.defineTags = function(dictionary) {
-  dictionary.defineTag('stability', {
-    mustHaveValue: true,
-    canHaveType: false,
-    canHaveName: true,
-    onTagged: function(doclet, tag) {
-      var level = tag.text;
-      if (levels.indexOf(level) >=0) {
-        doclet.stability = level;
-      } else {
-        var errorText = util.format('Invalid stability level (%s) in %s line %s', tag.text, doclet.meta.filename, doclet.meta.lineno);
-        require('jsdoc/util/error').handle( new Error(errorText) );
-      }
-    }
-  })
-};

apidoc/plugins/todo.js

@@ -6,8 +6,8 @@ exports.defineTags = function(dictionary) {
     canHaveName: true,
     onTagged: function(doclet, tag) {
       var parts = tag.text.split(' ');
-      if (parts[0] === 'stability') {
-        doclet.stability = parts.slice(1).join(' ');
+      if (parts[0] === 'api') {
+        doclet.stability = parts.slice(1).join(' ') || 'experimental';
       } else if (parts[0] === 'observable') {
         if (!doclet.observables) {
           doclet.observables = [];

apidoc/plugins/typedefs.js

@@ -0,0 +1,61 @@
+/*
+ * Converts olx.js @type annotations into properties of the previous @typedef.
+ * Changes @enum annotations into @typedef.
+ */
+
+var lastOlxTypedef = null;
+var olxTypes = {};
+
+function addSubparams(params) {
+  for (var j = 0, jj = params.length; j < jj; ++j) {
+    var param = params[j];
+    var types = param.type.names;
+    for (var k = 0, kk = types.length; k < kk; ++k) {
+      var name = types[k];
+      if (name in olxTypes) {
+        param.subparams = olxTypes[name];
+        // TODO Change template before recursing here, because the table gets
+        // too wide.
+        //addSubparams(param.subparams);
+        // TODO Do we need to support multiple object literal types per
+        // param?
+        break;
+      }
+    }
+  }
+}
+
+exports.handlers = {
+
+  newDoclet: function(e) {
+    var doclet = e.doclet;
+    if (doclet.meta.filename == 'olx.js') {
+      if (doclet.kind == 'typedef') {
+        lastOlxTypedef = doclet;
+        olxTypes[doclet.longname] = [];
+        doclet.properties = [];
+      } else if (lastOlxTypedef && doclet.memberof == lastOlxTypedef.longname) {
+        lastOlxTypedef.properties.push(doclet);
+        olxTypes[lastOlxTypedef.longname].push(doclet);
+      } else {
+        lastOlxTypedef = null;
+      }
+    } else if (doclet.isEnum) {
+      // We never export enums, so we document them like typedefs
+      doclet.kind = 'typedef';
+      delete doclet.isEnum;
+    }
+  },
+
+  parseComplete: function(e) {
+    var doclets = e.doclets;
+    for (var i = doclets.length - 1; i >= 0; --i) {
+      var doclet = doclets[i];
+      var params = doclet.params;
+      if (params) {
+        addSubparams(params);
+      }
+    }
+  }
+
+};

apidoc/readme.md

@@ -0,0 +1,74 @@
+# API Documentation
+
+This directory contains configuration (`conf.json`), static content (`index.md`), template (`template/`) and plugins (`plugins/`) for the [JSDoc3](http://usejsdoc.org/) API generator.
+
+## Documenting the source code
+
+JSDoc annotations are used for metadata used by the compiler, for defining the user facing API, and for user documentation.
+
+In the simplest case, a JSDoc block can look like this:
+```js
+/**
+ * Add the given control to the map.
+ * @param {ol.control.Control} control Control.
+ * @todo api
+ */
+ol.Map.prototype.addControl = function(control) {
+  // ...
+};
+```
+The first line is text for the user documentation. This can be long, and it can
+contain Markdown.
+
+The second line tells the Closure compiler the type of the argument.
+
+The third line (`@todo api`) marks the method as exportable. The stability can be added as value, e.g. `@todo api stable`. Once the documentation story is fully settled, we will remove the `todo ` and just write `@api` or `@api stable`. Without such an api note, the method will not be exported and not documented in the generated API documentation.
+
+### Events
+
+Events are documented using `@fires` and `@event` annotations:
+```js
+/**
+ * Constants for event names.
+ * @enum {string}
+ */
+ol.MapBrowserEvent.EventType = {
+  /**
+   * A true single click with no dragging and no double click. Note that this
+   * event is delayed by 250 ms to ensure that it is not a double click.
+   * @event ol.MapBrowserEvent#singleclick
+   * @todo api
+   */
+  SINGLECLICK: 'singleclick',
+  // ...
+};
+```
+Note the value of the `@event` annotation. The text before the hash refers to the event class that the event belongs to, and the text after the hash is the type of the event.
+
+To export event properties, they need to be defined in `externs/oli.js` (also see `readme.md` in `externs/`) and marked with an @api annotation:
+```js
+/** @interface */
+oli.MapBrowserEvent;
+
+/**
+ * @type {ol.Coordinate}
+ * @todo api
+ */
+oli.MapBrowserEvent.prototype.coordinate;
+
+// ...
+
+};
+```
+To document which events are fired by a class or method, the `@fires` annotation is used:
+```js
+ * @fires {@link ol.MapBrowserEvent} ol.MapBrowserEvent
+ * @fires {@link ol.MapEvent} ol.MapEvent
+ * @fires {@link ol.render.Event} ol.render.Event
+ * ...
+ */
+ol.Map = function(options) {
+  // ...
+};
+```
+Again, note the syntax of the `@fires` annotation. The link is necessary to provide a link to the documentation of the event, and the name of the event class is necessary for JSDoc3 to know which event we are talking about.

apidoc/template/tmpl/container.tmpl

@@ -27,7 +27,7 @@
     <?js if (doc.kind === 'module' && doc.module) { ?>
         <?js= self.partial('method.tmpl', doc.module) ?>
     <?js } ?>
-    <?js if (!doc.unexported && doc.kind === 'class') { ?>
+    <?js if (doc.kind === 'class' && !doc.hideConstructor && !doc.interface) { ?>
         <?js= self.partial('method.tmpl', doc) ?>
     <?js } else { ?>
         <?js if (doc.description) { ?>
@@ -47,7 +47,8 @@
         <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, a) ?>
+              <?js= (doc.implements&&doc.implements.indexOf(a)>-1?'(Interface)':'') ?></li>
         <?js }); ?></ul>
     <?js } ?>
     
@@ -141,7 +142,7 @@
         <h3 class="subsection-title">TypeDefs</h3>
         
         <dl><?js typedefs.forEach(function(e) { ?>
-            <?js= self.partial('members.tmpl', e) ?>
+            <?js= self.partial(e.params ? 'method.tmpl' : 'members.tmpl', e) ?>
         <?js }); ?></dl>
     <?js } ?>
     

bin/generate-exports.py

@@ -1,97 +0,0 @@
-#!/usr/bin/env python
-
-from operator import attrgetter
-from optparse import OptionParser
-import re
-import sys
-
-
-def simplerepr(obj):
-    keys = sorted(key for key in obj.__dict__.keys() if not key.startswith('_'))
-    attrs = ''.join(' %s=%r' % (key, obj.__dict__[key]) for key in keys)
-    return '<%s%s>' % (obj.__class__.__name__, attrs)
-
-
-class Exportable(object):
-
-    def __init__(self, name):
-        self.name = name
-
-    __repr__ = simplerepr
-
-    def export(self):
-        return ''
-
-
-class Symbol(Exportable):
-
-    def __init__(self, name, export_symbol):
-        Exportable.__init__(self, name)
-        self.export_symbol = export_symbol
-        self.props = set()
-
-    __repr__ = simplerepr
-
-    def export(self):
-        lines = []
-        if self.export_symbol:
-            lines.append('\n\ngoog.exportSymbol(\n    \'%s\',\n    %s);\n' % (self.name, self.name))
-        lines.extend('goog.exportProperty(\n    %s,\n    \'%s\',\n    %s.%s);\n' % (self.name, prop, self.name, prop) for prop in sorted(self.props))
-        return ''.join(lines)
-
-
-def main(argv):
-
-    option_parser = OptionParser()
-    option_parser.add_option('--exports', action='store_true')
-    options, args = option_parser.parse_args(argv[1:])
-
-    objects = {}
-    requires = set()
-    for arg in args:
-        for line in open(arg, 'rU'):
-            line = line.strip()
-            if not line:
-                continue
-            m = re.match(r'@exportProperty\s+(?P<prop>\S+)\Z', line)
-            if m:
-                components = m.group('prop').split('.')
-                if components[-2] == 'prototype':
-                    requires.add('.'.join(components[:-2]))
-                else:
-                    requires.add('.'.join(components[:-1]))
-                name = '.'.join(components[:-1]) 
-                prop = components[-1]
-                if name in objects:
-                    symbol = objects[name]
-                else:
-                    symbol = Symbol(name, False)
-                    objects[name] = symbol
-                symbol.props.add(prop)
-                continue
-            m = re.match(r'@exportSymbol\s+(?P<name>\S+)\Z', line)
-            if m:
-                name = m.group('name')
-                if name in objects:
-                    raise RuntimeError(line)  # Name already defined
-                symbol = Symbol(name, True)
-                objects[name] = symbol
-                components = m.group('name').split('.')
-                if re.match(r'[A-Z]', components[-1]):
-                    requires.add(name)
-                else:
-                    requires.add('.'.join(components[:-1]))
-                continue
-            raise RuntimeError(line)
-
-    objects = sorted(objects.values(), key=attrgetter('name'))
-
-    if options.exports:
-        if requires:
-            for require in sorted(requires):
-                sys.stdout.write('goog.require(\'%s\');\n' % (require,))
-        for obj in objects:
-            sys.stdout.write(obj.export())
-
-if __name__ == '__main__':
-    sys.exit(main(sys.argv))

build.py

@@ -86,11 +86,7 @@ EXECUTABLES = [variables.GIT, variables.GJSLINT, variables.JAVA, variables.JAR,
                variables.JSDOC, variables.JSHINT, variables.PYTHON,
                variables.PHANTOMJS]
 
-EXPORTS = [path
-           for path in ifind('src')
-           if path.endswith('.exports')]
-
-EXTERNAL_SRC = ['build/src/external/src/exports.js']
+EXPORTS = 'build/exports.js'
 
 EXAMPLES = [path
             for path in ifind('examples')
@@ -113,8 +109,6 @@ EXAMPLES_JSON = ['build/' + example.replace('.html', '.json')
 EXAMPLES_COMBINED = ['build/' + example.replace('.html', '.combined.js')
                      for example in EXAMPLES]
 
-INTERNAL_SRC = ['build/src/internal/src/requireall.js']
-
 GLSL_SRC = [path
             for path in ifind('src')
             if path.endswith('.glsl')]
@@ -182,15 +176,15 @@ def build_ol_css(t):
     t.touch()
 
 
-@target('build/ol.js', PLOVR_JAR, SRC, EXTERNAL_SRC, SHADER_SRC,
-        LIBTESS_JS_SRC, 'buildcfg/base.json', 'buildcfg/ol.json')
+@target('build/ol.js', PLOVR_JAR, SRC, EXPORTS, SHADER_SRC, LIBTESS_JS_SRC,
+        'buildcfg/base.json', 'buildcfg/ol.json')
 def build_ol_js(t):
     t.output('%(JAVA)s', '-server', '-XX:+TieredCompilation', '-jar',
             PLOVR_JAR, 'build', 'buildcfg/ol.json')
     report_sizes(t)
 
 
-@target('build/ol-simple.js', PLOVR_JAR, SRC, INTERNAL_SRC, SHADER_SRC,
+@target('build/ol-simple.js', PLOVR_JAR, SRC, EXPORTS, SHADER_SRC,
         LIBTESS_JS_SRC, 'buildcfg/base.json', 'buildcfg/ol.json',
         'buildcfg/ol-simple.json')
 def build_ol_simple_js(t):
@@ -199,8 +193,8 @@ def build_ol_simple_js(t):
     report_sizes(t)
 
 
-@target('build/ol-whitespace.js', PLOVR_JAR, SRC, INTERNAL_SRC, SHADER_SRC,
-        LIBTESS_JS_SRC, 'buildcfg/base.json', 'buildcfg/ol.json',
+@target('build/ol-whitespace.js', PLOVR_JAR, SRC, EXPORTS,
+        SHADER_SRC, LIBTESS_JS_SRC, 'buildcfg/base.json', 'buildcfg/ol.json',
         'buildcfg/ol-whitespace.json')
 def build_ol_whitespace_js(t):
     t.output('%(JAVA)s', '-server', '-XX:+TieredCompilation', '-jar',
@@ -211,17 +205,16 @@ def build_ol_whitespace_js(t):
 virtual('build-all', 'build/ol-all.js')
 
 
-@target('build/ol-all.js', PLOVR_JAR, SRC, EXTERNAL_SRC, INTERNAL_SRC,
-        SHADER_SRC, LIBTESS_JS_SRC, 'buildcfg/base.json',
-        'buildcfg/ol-all.json')
+@target('build/ol-all.js', PLOVR_JAR, SRC, EXPORTS, SHADER_SRC, LIBTESS_JS_SRC,
+        'buildcfg/base.json', 'buildcfg/ol-all.json')
 def build_ol_all_js(t):
     t.output('%(JAVA)s', '-server', '-XX:+TieredCompilation', '-jar',
             PLOVR_JAR, 'build', 'buildcfg/ol-all.json')
 
 
-@target('build/src/external/src/exports.js', 'bin/generate-exports.py', EXPORTS)
-def build_src_external_src_exports_js(t):
-    t.output('%(PYTHON)s', 'bin/generate-exports.py', '--exports', EXPORTS)
+@target(EXPORTS, SRC)
+def build_exports_js(t):
+    t.run('node', 'tasks/generate-exports.js', EXPORTS)
 
 
 for glsl_src in GLSL_SRC:
@@ -236,29 +229,19 @@ for glsl_src in GLSL_SRC:
     shader_src_helper(glsl_src)
 
 
-def _build_require_list(dependencies, output_file_name):
+@target('build/test/requireall.js', SPEC)
+def build_test_requireall_js(t):
     requires = set()
-    for dependency in dependencies:
+    for dependency in t.dependencies:
         for line in open(dependency, 'rU'):
             match = re.match(r'goog\.provide\(\'(.*)\'\);', line)
             if match:
                 requires.add(match.group(1))
-    with open(output_file_name, 'wb') as f:
+    with open(t.name, 'wb') as f:
         for require in sorted(requires):
             f.write('goog.require(\'%s\');\n' % (require,))
 
 
-@target('build/src/internal/src/requireall.js', SRC, SHADER_SRC,
-        LIBTESS_JS_SRC)
-def build_src_internal_src_requireall_js(t):
-    _build_require_list(t.dependencies, t.name)
-
-
-@target('build/test/requireall.js', SPEC)
-def build_test_requireall_js(t):
-    _build_require_list(t.dependencies, t.name)
-
-
 virtual('build-examples', 'examples', 'build/examples/all.combined.js',
         EXAMPLES_COMBINED)
 
@@ -277,7 +260,7 @@ def examples_examples_list_js(t):
 
 
 @target('build/examples/all.combined.js', 'build/examples/all.js', PLOVR_JAR,
-        SRC, INTERNAL_SRC, SHADER_SRC, LIBTESS_JS_SRC,
+        SRC, SHADER_SRC, LIBTESS_JS_SRC,
         'buildcfg/base.json', 'build/examples/all.json')
 def build_examples_all_combined_js(t):
     t.output('%(JAVA)s', '-server', '-XX:+TieredCompilation', '-jar',
@@ -332,7 +315,7 @@ def examples_star_combined_js(name, match):
                 PLOVR_JAR, 'build', 'build/examples/%(id)s.json' %
                 match.groupdict())
         report_sizes(t)
-    dependencies = [PLOVR_JAR, SRC, INTERNAL_SRC, SHADER_SRC, LIBTESS_JS_SRC,
+    dependencies = [PLOVR_JAR, SRC, SHADER_SRC, LIBTESS_JS_SRC,
                     'buildcfg/base.json',
                     'examples/%(id)s.js' % match.groupdict(),
                     'build/examples/%(id)s.json' % match.groupdict()]
@@ -345,18 +328,17 @@ def serve(t):
           'buildcfg/ol-all.json', EXAMPLES_JSON, 'buildcfg/test.json')
 
 
-@target('serve-integration-test', PLOVR_JAR, INTERNAL_SRC)
+@target('serve-integration-test', PLOVR_JAR)
 def serve_precommit(t):
     t.run('%(JAVA)s', '-jar', PLOVR_JAR, 'serve',
           'buildcfg/ol-all.json', 'buildcfg/test.json')
 
 
-virtual('lint', 'build/lint-timestamp', 'build/lint-generated-timestamp',
-        'build/lint-libtess.js-timestamp', 'build/check-requires-timestamp',
-        'build/check-whitespace-timestamp')
+virtual('lint', 'build/lint-timestamp', 'build/lint-libtess.js-timestamp',
+        'build/check-requires-timestamp', 'build/check-whitespace-timestamp')
 
 
-@target('build/lint-timestamp', SRC, EXAMPLES_SRC, SPEC, precious=True)
+@target('build/lint-timestamp', SRC, EXPORTS, EXAMPLES_SRC, SPEC, precious=True)
 def build_lint_src_timestamp(t):
     t.run('%(GJSLINT)s',
           '--jslint_error=all',
@@ -366,26 +348,6 @@ def build_lint_src_timestamp(t):
     t.touch()
 
 
-@target('build/lint-generated-timestamp', INTERNAL_SRC, EXTERNAL_SRC,
-        precious=True)
-def build_lint_generated_timestamp(t):
-    limited_doc_files = [
-        path
-        for path in ifind('externs')
-        if path.endswith('.js')]
-    t.run('%(GJSLINT)s',
-          '--jslint_error=all',
-          # ignore error for max line length (for these auto-generated sources)
-          '--disable=110',
-          '--custom_jsdoc_tags=todo',
-          # for a complete list of error codes to allow, see
-          # http://closure-linter.googlecode.com/svn/trunk/closure_linter/errors.py
-          '--limited_doc_files=%s' % (','.join(limited_doc_files),),
-          '--strict',
-          t.newer(t.dependencies))
-    t.touch()
-
-
 @target('build/lint-libtess.js-timestamp', LIBTESS_JS_SRC, precious=True)
 def build_lint_libtess_js_timestamp(t):
     t.run('%(GJSLINT)s',
@@ -398,8 +360,8 @@ def build_lint_libtess_js_timestamp(t):
 
 virtual('jshint', 'build/jshint-timestamp')
 
-
-@target('build/jshint-timestamp', SRC, EXAMPLES_SRC, SPEC, precious=True)
+@target('build/jshint-timestamp', SRC, EXPORTS, EXAMPLES_SRC, SPEC,
+        precious=True)
 def build_jshint_timestamp(t):
     t.run(variables.JSHINT, '--verbose', t.newer(t.dependencies))
     t.touch()
@@ -428,8 +390,8 @@ def _strip_comments(lines):
                 yield lineno, line
 
 
-@target('build/check-requires-timestamp', SRC, INTERNAL_SRC, EXTERNAL_SRC,
-        EXAMPLES_SRC, SHADER_SRC, LIBTESS_JS_SRC, SPEC)
+@target('build/check-requires-timestamp', SRC, EXAMPLES_SRC,
+        SHADER_SRC, LIBTESS_JS_SRC, SPEC)
 def build_check_requires_timestamp(t):
     from zipfile import ZipFile
     unused_count = 0
@@ -448,8 +410,6 @@ def build_check_requires_timestamp(t):
                 if m:
                     all_provides.add(m.group(1))
     for filename in sorted(t.dependencies):
-        if filename == 'build/src/internal/src/requireall.js':
-            continue
         require_linenos = {}
         uses = set()
         lines = open(filename, 'rU').readlines()
@@ -529,8 +489,6 @@ def build_check_requires_timestamp(t):
                    for key, child in root.children.iteritems()]
     missing_count = 0
     for filename in sorted(t.dependencies):
-        if filename in INTERNAL_SRC or filename in EXTERNAL_SRC:
-            continue
         provides = set()
         requires = set()
         uses = set()
@@ -573,9 +531,8 @@ def build_check_requires_timestamp(t):
     t.touch()
 
 
-@target('build/check-whitespace-timestamp', SRC, INTERNAL_SRC, EXTERNAL_SRC,
-        EXAMPLES_SRC, SPEC, EXPORTS, JSDOC_SRC, LIBTESS_JS_SRC,
-        precious=True)
+@target('build/check-whitespace-timestamp', SRC, EXPORTS, EXAMPLES_SRC,
+        SPEC, JSDOC_SRC, LIBTESS_JS_SRC, precious=True)
 def build_check_whitespace_timestamp(t):
     CR_RE = re.compile(r'\r')
     LEADING_WHITESPACE_RE = re.compile(r'\s+')
@@ -622,7 +579,7 @@ virtual('apidoc', 'build/jsdoc-%(BRANCH)s-timestamp' % vars(variables))
 
 
 @target('build/jsdoc-%(BRANCH)s-timestamp' % vars(variables), 'host-resources',
-        'build/src/external/src/exports.js', SRC, SHADER_SRC,
+        EXPORTS, SRC, SHADER_SRC,
         ifind('apidoc/template'))
 def jsdoc_BRANCH_timestamp(t):
     t.run('%(JSDOC)s', 'apidoc/index.md', '-c', 'apidoc/conf.json',
@@ -735,7 +692,7 @@ def proj4js_zip(t):
     t.info('downloaded %r', t.name)
 
 
-virtual('test-deps', INTERNAL_SRC, PROJ4JS, 'build/test/requireall.js')
+virtual('test-deps', PROJ4JS, 'build/test/requireall.js')
 
 
 @target('test', 'test-deps', phony=True)

buildcfg/base.json

@@ -68,7 +68,6 @@
   ],
 
   "paths": [
-    "../build/src/internal/src",
     "../src"
   ],
 

buildcfg/jsdoc/symbols/conf.json

@@ -0,0 +1,15 @@
+{
+    "opts": {
+        "recurse": true,
+        "template": "buildcfg/jsdoc/symbols"
+    },
+    "tags": {
+        "allowUnknownTags": true
+    },
+    "source": {
+        "includePattern": "\\.js$"
+    },
+    "plugins": [
+        "buildcfg/jsdoc/symbols/todo-plugin"
+    ]
+}

buildcfg/jsdoc/symbols/publish.js

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Generates JSON output based on doclets with the "api" tag.
+ */
+var assert = require('assert');
+var fs = require('fs');
+var path = require('path');
+
+
+/**
+ * Publish hook for the JSDoc template.  Writes to JSON stdout.
+ * @param {function} data The root of the Taffy DB containing doclet records.
+ * @param {Object} opts Options.
+ */
+exports.publish = function(data, opts) {
+  var cwd = process.cwd();
+
+  // get all doclets with the "api" property, but no enums, typedefs and events.
+  var docs = data(
+      {api: {isString: true}},
+      {isEnum: {'!is': true}},
+      {kind: {'!is': 'typedef'}},
+      {kind: {'!is': 'event'}}
+      ).get();
+
+  // get symbols data, filter out those that are members of private classes
+  var symbols = docs.filter(function(doc) {
+    var include = true;
+    var constructor = doc.memberof;
+    if (constructor && constructor.substr(-1) === '_') {
+      assert.strictEqual(doc.inherited, true,
+          'Unexpected export on private class: ' + doc.longname);
+      include = false;
+    }
+    return include;
+  }).map(function(doc) {
+    return {
+      name: doc.longname,
+      extends: doc.augments,
+      path: path.join(doc.meta.path, doc.meta.filename)
+    };
+  });
+
+  process.stdout.write(JSON.stringify({symbols: symbols}, null, 2));
+
+};

buildcfg/jsdoc/symbols/todo-plugin.js

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview  This plugin should go away when we get rid of Plovr and can
+ * use Closure Compiler's extra_annotation_name option.  Until then, we hijack
+ * the todo tag to add doclet properties for other tags we eventually want to
+ * support.  For example, the "todo api" tag can eventually be replaced with
+ * the "api" tag.
+ */
+
+
+/**
+ * Our hook to define new tags.
+ * @param {Object} dictionary The tag dictionary.
+ */
+exports.defineTags = function(dictionary) {
+
+  dictionary.defineTag('todo', {
+    mustHaveValue: true,
+    onTagged: function(doclet, tag) {
+      var parts = tag.text.split(' ');
+      if (parts[0] === 'api') {
+        doclet.api = parts.slice(1).join(' ').trim();
+      }
+    }
+  });
+
+};

buildcfg/ol-all.json

@@ -17,8 +17,7 @@
   "inherits": "base.json",
 
   "inputs": [
-    "../build/src/internal/src/requireall.js",
-    "../build/src/external/src/exports.js"
+    "../build/exports.js"
   ]
 
 }

buildcfg/ol-simple.json

@@ -27,8 +27,7 @@
   "inherits": "ol.json",
 
   "inputs": [
-    "../build/src/internal/src/requireall.js",
-    "../build/src/external/src/exports.js"
+    "../build/exports.js"
   ],
 
   "mode": "SIMPLE",

buildcfg/ol-whitespace.json

@@ -28,7 +28,7 @@
   "inherits": "ol.json",
 
   "inputs": [
-    "../build/src/internal/src/requireall.js"
+    "../build/exports.js"
   ],
 
   "mode": "WHITESPACE",

buildcfg/ol.json

@@ -27,7 +27,7 @@
   "inherits": "base.json",
 
   "inputs": [
-    "../build/src/external/src/exports.js"
+    "../build/exports.js"
   ],
 
   "output-wrapper": "// OpenLayers 3. see http://ol3js.org/\n(function(){%output%})();",

externs/oli.js

@@ -14,7 +14,11 @@ var oli;
 oli.CollectionEvent;
 
 
-/** @type {*} */
+/**
+ * The element that is added to or removed from the collection.
+ * @type {*}
+ * @todo api
+ */
 oli.CollectionEvent.prototype.element;
 
 
@@ -23,7 +27,10 @@ oli.CollectionEvent.prototype.element;
 oli.DragBoxEvent;
 
 
-/** @type {ol.Coordinate} */
+/**
+ * @type {ol.Coordinate}
+ * @todo api
+ */
 oli.DragBoxEvent.prototype.coordinate;
 
 
@@ -32,7 +39,11 @@ oli.DragBoxEvent.prototype.coordinate;
 oli.DrawEvent;
 
 
-/** @type {ol.Feature} */
+/**
+ * The feature being drawn.
+ * @type {ol.Feature}
+ * @todo api
+ */
 oli.DrawEvent.prototype.feature;
 
 
@@ -77,7 +88,10 @@ oli.FrameState.prototype.layerStatesArray;
 oli.FrameState.prototype.logos;
 
 
-/** @type {number} */
+/**
+ * @type {number}
+ * @todo api
+ */
 oli.FrameState.prototype.pixelRatio;
 
 
@@ -101,7 +115,10 @@ oli.FrameState.prototype.skippedFeatureUids_;
 oli.FrameState.prototype.tileQueue;
 
 
-/** @type {number} */
+/**
+ * @type {number}
+ * @todo api
+ */
 oli.FrameState.prototype.time;
 
 
@@ -109,7 +126,10 @@ oli.FrameState.prototype.time;
 oli.FrameState.prototype.usedTiles;
 
 
-/** @type {oli.View2DState} */
+/**
+ * @type {oli.View2DState}
+ * @todo api
+ */
 oli.FrameState.prototype.view2DState;
 
 
@@ -135,15 +155,24 @@ oli.ObjectEvent.prototype.key;
 oli.MapBrowserEvent;
 
 
-/** @type {ol.Coordinate} */
+/**
+ * @type {ol.Coordinate}
+ * @todo api
+ */
 oli.MapBrowserEvent.prototype.coordinate;
 
 
-/** @type {Event} */
+/**
+ * @type {Event}
+ * @todo api
+ */
 oli.MapBrowserEvent.prototype.originalEvent;
 
 
-/** @type {ol.Pixel} */
+/**
+ * @type {ol.Pixel}
+ * @todo api
+ */
 oli.MapBrowserEvent.prototype.pixel;
 
 
@@ -187,15 +216,24 @@ oli.control.Control.prototype.setMap = function(map) {};
 oli.interaction.DragAndDropEvent;
 
 
-/** @type {Array.<ol.Feature>} */
+/**
+ * @type {Array.<ol.Feature>|undefined}
+ * @todo api
+ */
 oli.interaction.DragAndDropEvent.prototype.features;
 
 
-/** @type {ol.proj.Projection} */
+/**
+ * @type {ol.proj.Projection|undefined}
+ * @todo api
+ */
 oli.interaction.DragAndDropEvent.prototype.projection;
 
 
-/** @type {File} */
+/**
+ * @type {File}
+ * @todo api
+ */
 oli.interaction.DragAndDropEvent.prototype.file;
 
 
@@ -203,19 +241,35 @@ oli.interaction.DragAndDropEvent.prototype.file;
 oli.render.Event;
 
 
-/** @type {CanvasRenderingContext2D|null|undefined} */
+/**
+ * Canvas context. Only available when a Canvas renderer is used, null
+ * otherwise.
+ * @type {CanvasRenderingContext2D|null|undefined}
+ * @todo api
+ */
 oli.render.Event.prototype.context;
 
 
-/** @type {oli.FrameState|undefined} */
+/**
+ * @type {oli.FrameState|undefined}
+ * @todo api
+ */
 oli.render.Event.prototype.frameState;
 
 
-/** @type {ol.webgl.Context|null|undefined} */
+/**
+ * WebGL context. Only available when a WebGL renderer is used, null otherwise.
+ * @type {ol.webgl.Context|null|undefined}
+ * @todo api
+ */
 oli.render.Event.prototype.glContext;
 
 
-/** @type {ol.render.IVectorContext|undefined} */
+/**
+ * For canvas, this is an instance of {@link ol.render.canvas.Immediate}.
+ * @type {ol.render.IVectorContext|undefined}
+ * @todo api
+ */
 oli.render.Event.prototype.vectorContext;
 
 
@@ -224,5 +278,9 @@ oli.render.Event.prototype.vectorContext;
 oli.source.VectorEvent;
 
 
-/** @type {ol.Feature} */
+/**
+ * The feature being added or removed.
+ * @type {ol.Feature}
+ * @todo api
+ */
 oli.source.VectorEvent.prototype.feature;

externs/olx.js

@@ -7,7 +7,7 @@ var olx;
 /**
  * @typedef {{html: string,
  *     tileRanges: (Object.<string, Array.<ol.TileRange>>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.AttributionOptions;
 
@@ -29,7 +29,7 @@ olx.AttributionOptions.prototype.tileRanges;
 /**
  * @typedef {{loadTilesWhileAnimating: (boolean|undefined),
  *     loadTilesWhileInteracting: (boolean|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.DeviceOptions;
 
@@ -52,7 +52,7 @@ olx.DeviceOptions.prototype.loadTilesWhileInteracting;
 
 /**
  * @typedef {{tracking: (boolean|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.DeviceOrientationOptions;
 
@@ -68,7 +68,7 @@ olx.DeviceOrientationOptions.prototype.tracking;
  * @typedef {{tracking: (boolean|undefined),
  *     trackingOptions: (GeolocationPositionOptions|undefined),
  *     projection: ol.proj.ProjectionLike}}
- * @todo stability experimental
+ * @todo api
  */
 olx.GeolocationOptions;
 
@@ -107,7 +107,7 @@ olx.GeolocationOptions.prototype.projection;
  *     renderer: (ol.RendererHint|Array.<ol.RendererHint|string>|string|undefined),
  *     target: (Element|string|undefined),
  *     view: (ol.IView|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.MapOptions;
 
@@ -155,7 +155,8 @@ olx.MapOptions.prototype.keyboardEventTarget;
 
 
 /**
- * Layers.
+ * Layers. Array or {@link ol.Collection} items are instances of
+ * {@link ol.layer.Layer} or any of its {@link ol.layer} subclasses.
  * @type {Array.<ol.layer.Base>|ol.Collection|undefined}
  */
 olx.MapOptions.prototype.layers;
@@ -205,7 +206,7 @@ olx.MapOptions.prototype.view;
  *     insertFirst: (boolean|undefined),
  *     offsetX: (number|undefined),
  *     offsetY: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.OverlayOptions;
 
@@ -271,7 +272,7 @@ olx.OverlayOptions.prototype.offsetY;
  * @typedef {{code: string,
  *     extent: (ol.Extent|undefined),
  *     global: (boolean|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.Proj4jsProjectionOptions;
 
@@ -304,7 +305,7 @@ olx.Proj4jsProjectionOptions.prototype.global;
  *     extent: (ol.Extent|undefined),
  *     axisOrientation: (string|undefined),
  *     global: (boolean|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.ProjectionOptions;
 
@@ -358,7 +359,7 @@ olx.ProjectionOptions.prototype.global;
  *     rotation: (number|undefined),
  *     zoom: (number|undefined),
  *     zoomFactor: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.View2DOptions;
 
@@ -471,7 +472,7 @@ olx.View2DOptions.prototype.zoomFactor;
  *     start: (number|undefined),
  *     duration: (number|undefined),
  *     easing: (function(number):number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.animation.BounceOptions;
 
@@ -510,7 +511,7 @@ olx.animation.BounceOptions.prototype.easing;
  *     start: (number|undefined),
  *     duration: (number|undefined),
  *     easing: (function(number):number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.animation.PanOptions;
 
@@ -549,7 +550,7 @@ olx.animation.PanOptions.prototype.easing;
  *     start: (number|undefined),
  *     duration: (number|undefined),
  *     easing: (function(number):number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.animation.RotateOptions;
 
@@ -596,7 +597,7 @@ olx.animation.RotateOptions.prototype.easing;
  *     start: (number|undefined),
  *     duration: (number|undefined),
  *     easing: (function(number):number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.animation.ZoomOptions;
 
@@ -633,7 +634,7 @@ olx.animation.ZoomOptions.prototype.easing;
 /**
  * @typedef {{className: (string|undefined),
  *     target: (Element|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.control.AttributionOptions;
 
@@ -655,7 +656,7 @@ olx.control.AttributionOptions.prototype.target;
 /**
  * @typedef {{element: (Element|undefined),
  *     target: (Element|string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.control.ControlOptions;
 
@@ -683,7 +684,7 @@ olx.control.ControlOptions.prototype.target;
  *     logoOptions: (olx.control.LogoOptions|undefined),
  *     zoom: (boolean|undefined),
  *     zoomOptions: (olx.control.ZoomOptions|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.control.DefaultsOptions;
 
@@ -735,7 +736,7 @@ olx.control.DefaultsOptions.prototype.zoomOptions;
  *     tipLabel: (string|undefined),
  *     keys: (boolean|undefined),
  *     target: (Element|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.control.FullScreenOptions;
 
@@ -771,7 +772,7 @@ olx.control.FullScreenOptions.prototype.target;
 /**
  * @typedef {{className: (string|undefined),
  *     target: (Element|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.control.LogoOptions;
 
@@ -796,7 +797,7 @@ olx.control.LogoOptions.prototype.target;
  *     projection: ol.proj.ProjectionLike,
  *     target: (Element|undefined),
  *     undefinedHTML: (string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.control.MousePositionOptions;
 
@@ -841,7 +842,7 @@ olx.control.MousePositionOptions.prototype.undefinedHTML;
  *     minWidth: (number|undefined),
  *     target: (Element|undefined),
  *     units: (ol.control.ScaleLineUnits|string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.control.ScaleLineOptions;
 
@@ -883,7 +884,7 @@ olx.control.ScaleLineOptions.prototype.units;
  *     zoomOutTipLabel: (string|undefined),
  *     delta: (number|undefined),
  *     target: (Element|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.control.ZoomOptions;
 
@@ -948,7 +949,7 @@ olx.control.ZoomOptions.prototype.target;
  * @typedef {{className: (string|undefined),
  *     maxResolution: (number|undefined),
  *     minResolution: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.control.ZoomSliderOptions;
 
@@ -979,7 +980,7 @@ olx.control.ZoomSliderOptions.prototype.minResolution;
  *     target: (Element|undefined),
  *     tipLabel: (string|undefined),
  *     extent: (ol.Extent|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.control.ZoomToExtentOptions;
 
@@ -1015,7 +1016,7 @@ olx.control.ZoomToExtentOptions.prototype.extent;
 
 /**
  * @typedef {{defaultProjection: ol.proj.ProjectionLike}}
- * @todo stability experimental
+ * @todo api
  */
 olx.format.GeoJSONOptions;
 
@@ -1029,7 +1030,7 @@ olx.format.GeoJSONOptions.prototype.defaultProjection;
 
 /**
  * @typedef {{defaultProjection: ol.proj.ProjectionLike}}
- * @todo stability experimental
+ * @todo api
  */
 olx.format.TopoJSONOptions;
 
@@ -1043,7 +1044,7 @@ olx.format.TopoJSONOptions.prototype.defaultProjection;
 
 /**
  * @typedef {{altitudeMode: (ol.format.IGCZ|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.format.IGCOptions;
 
@@ -1058,7 +1059,7 @@ olx.format.IGCOptions.prototype.altitudeMode;
 
 /**
  * @typedef {{defaultStyle: (Array.<ol.style.Style>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.format.KMLOptions;
 
@@ -1079,7 +1080,7 @@ olx.format.KMLOptions.prototype.defaultStyle;
  *     multiCurve: (boolean|undefined),
  *     multiSurface: (boolean|undefined),
  *     schemaLocation: (string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.format.GMLOptions;
 
@@ -1149,7 +1150,7 @@ olx.format.GMLOptions.prototype.schemaLocation;
  * @typedef {{featureNS: string,
  *     featureType: string,
  *     schemaLocation: (string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.format.WFSOptions;
 
@@ -1186,7 +1187,7 @@ olx.format.WFSOptions.prototype.schemaLocation;
  *     maxFeatures: (number|undefined),
  *     geometryName: (string|undefined),
  *     bbox: (ol.Extent|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.format.WFSWriteGetFeatureOptions;
 
@@ -1262,7 +1263,7 @@ olx.format.WFSWriteGetFeatureOptions.prototype.bbox;
  *     srsName: (string|undefined),
  *     handle: (string|undefined),
  *     nativeElements: Array.<Object>}}
- * @todo stability experimental
+ * @todo api
  */
 olx.format.WFSWriteTransactionOptions;
 
@@ -1322,7 +1323,7 @@ olx.format.WFSWriteTransactionOptions.prototype.nativeElements;
  *     pinchZoom: (boolean|undefined),
  *     zoomDelta: (number|undefined),
  *     zoomDuration: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.DefaultsOptions;
 
@@ -1400,7 +1401,7 @@ olx.interaction.DefaultsOptions.prototype.zoomDuration;
 /**
  * @typedef {{duration: (number|undefined),
  *     delta: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.DoubleClickZoomOptions;
 
@@ -1422,7 +1423,7 @@ olx.interaction.DoubleClickZoomOptions.prototype.delta;
 /**
  * @typedef {{formatConstructors: (Array.<function(new: ol.format.Feature)>|undefined),
  *     reprojectTo: ol.proj.ProjectionLike}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.DragAndDropOptions;
 
@@ -1444,7 +1445,7 @@ olx.interaction.DragAndDropOptions.prototype.reprojectTo;
 /**
  * @typedef {{condition: (ol.events.ConditionType|undefined),
  *     style: ol.style.Style}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.DragBoxOptions;
 
@@ -1466,7 +1467,7 @@ olx.interaction.DragBoxOptions.prototype.style;
 
 /**
  * @typedef {{kinetic: (ol.Kinetic|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.DragPanOptions;
 
@@ -1480,7 +1481,7 @@ olx.interaction.DragPanOptions.prototype.kinetic;
 
 /**
  * @typedef {{condition: (ol.events.ConditionType|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.DragRotateAndZoomOptions;
 
@@ -1495,7 +1496,7 @@ olx.interaction.DragRotateAndZoomOptions.prototype.condition;
 
 /**
  * @typedef {{condition: (ol.events.ConditionType|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.DragRotateOptions;
 
@@ -1511,7 +1512,7 @@ olx.interaction.DragRotateOptions.prototype.condition;
 /**
  * @typedef {{condition: (ol.events.ConditionType|undefined),
  *     style: ol.style.Style}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.DragZoomOptions;
 
@@ -1538,7 +1539,7 @@ olx.interaction.DragZoomOptions.prototype.style;
  *     type: ol.geom.GeometryType,
  *     minPointsPerRing: (number|undefined),
  *     style: (ol.style.Style|Array.<ol.style.Style>|ol.feature.StyleFunction|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.DrawOptions;
 
@@ -1590,7 +1591,7 @@ olx.interaction.DrawOptions.prototype.style;
 /**
  * @typedef {{condition: (ol.events.ConditionType|undefined),
  *     pixelDelta: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.KeyboardPanOptions;
 
@@ -1614,7 +1615,7 @@ olx.interaction.KeyboardPanOptions.prototype.pixelDelta;
  * @typedef {{duration: (number|undefined),
  *     condition: (ol.events.ConditionType|undefined),
  *     delta: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.KeyboardZoomOptions;
 
@@ -1646,7 +1647,7 @@ olx.interaction.KeyboardZoomOptions.prototype.delta;
  *     pixelTolerance: (number|undefined),
  *     style: (ol.style.Style|Array.<ol.style.Style>|ol.feature.StyleFunction|undefined),
  *     features: ol.Collection}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.ModifyOptions;
 
@@ -1683,7 +1684,7 @@ olx.interaction.ModifyOptions.prototype.features;
 
 /**
  * @typedef {{duration: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.MouseWheelZoomOptions;
 
@@ -1697,7 +1698,7 @@ olx.interaction.MouseWheelZoomOptions.prototype.duration;
 
 /**
  * @typedef {{threshold: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.PinchRotateOptions;
 
@@ -1711,7 +1712,7 @@ olx.interaction.PinchRotateOptions.prototype.threshold;
 
 /**
  * @typedef {{duration: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.PinchZoomOptions;
 
@@ -1730,7 +1731,7 @@ olx.interaction.PinchZoomOptions.prototype.duration;
  *     style: (ol.style.Style|Array.<ol.style.Style>|ol.feature.StyleFunction|undefined),
  *     removeCondition: (ol.events.ConditionType|undefined),
  *     toggleCondition: (ol.events.ConditionType|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.interaction.SelectOptions;
 
@@ -1797,7 +1798,7 @@ olx.interaction.SelectOptions.prototype.toggleCondition;
  *     visible: (boolean|undefined),
  *     minResolution: (number|undefined),
  *     maxResolution: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.layer.BaseOptions;
 
@@ -1868,7 +1869,7 @@ olx.layer.BaseOptions.prototype.maxResolution;
  *     visible: (boolean|undefined),
  *     minResolution: (number|undefined),
  *     maxResolution: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.layer.LayerOptions;
 
@@ -1946,7 +1947,7 @@ olx.layer.LayerOptions.prototype.maxResolution;
  *     minResolution: (number|undefined),
  *     maxResolution: (number|undefined),
  *     layers: (Array.<ol.layer.Base>|ol.Collection|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.layer.GroupOptions;
 
@@ -2029,7 +2030,7 @@ olx.layer.GroupOptions.prototype.layers;
  *     saturation: (number|undefined),
  *     source: ol.source.Vector,
  *     visible: (boolean|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.layer.HeatmapOptions;
 
@@ -2147,7 +2148,7 @@ olx.layer.HeatmapOptions.prototype.visible;
  *     minResolution: (number|undefined),
  *     maxResolution: (number|undefined),
  *     useInterimTilesOnError: (boolean|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.layer.TileOptions;
 
@@ -2241,7 +2242,7 @@ olx.layer.TileOptions.prototype.useInterimTilesOnError;
  *     source: ol.source.Vector,
  *     style: (ol.style.Style|Array.<ol.style.Style>|ol.feature.StyleFunction|undefined),
  *     visible: (boolean|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.layer.VectorOptions;
 
@@ -2329,7 +2330,7 @@ olx.layer.VectorOptions.prototype.visible;
  * @typedef {{features: (Array.<ol.Feature>|ol.Collection|undefined),
  *     map: (ol.Map|undefined),
  *     style: (ol.style.Style|Array.<ol.style.Style>|ol.feature.StyleFunction|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.FeatureOverlayOptions;
 
@@ -2360,7 +2361,7 @@ olx.FeatureOverlayOptions.prototype.style;
  *     key: string,
  *     imagerySet: string,
  *     tileLoadFunction: (ol.TileLoadFunctionType|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.BingMapsOptions;
 
@@ -2399,7 +2400,7 @@ olx.source.BingMapsOptions.prototype.tileLoadFunction;
  *     format: ol.format.Feature,
  *     logo: (string|undefined),
  *     projection: ol.proj.ProjectionLike}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.FormatVectorOptions;
 
@@ -2449,7 +2450,7 @@ olx.source.FormatVectorOptions.prototype.projection;
  *     text: (string|undefined),
  *     url: (string|undefined),
  *     urls: (Array.<string>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.GeoJSONOptions;
 
@@ -2528,7 +2529,7 @@ olx.source.GeoJSONOptions.prototype.urls;
  *     text: (string|undefined),
  *     url: (string|undefined),
  *     urls: (Array.<string>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.GPXOptions;
 
@@ -2610,7 +2611,7 @@ olx.source.GPXOptions.prototype.urls;
  *            tileGrid: (ol.tilegrid.TileGrid|undefined),
  *            tileLoadFunction: (ol.TileLoadFunctionType|undefined),
  *            tileUrlFunction: (ol.TileUrlFunctionType|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.TileImageOptions;
 
@@ -2698,7 +2699,7 @@ olx.source.TileImageOptions.prototype.tileUrlFunction;
  *     tileUrlFunction: (ol.TileUrlFunctionType|undefined),
  *     url: (string|undefined),
  *     urls: (Array.<string>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.TileVectorOptions;
 
@@ -2784,7 +2785,7 @@ olx.source.TileVectorOptions.prototype.urls;
  *     projection: ol.proj.ProjectionLike,
  *     text: (string|undefined),
  *     url: (string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.TopoJSONOptions;
 
@@ -2852,7 +2853,7 @@ olx.source.TopoJSONOptions.prototype.url;
  *     text: (string|undefined),
  *     url: (string|undefined),
  *     urls: (Array.<string>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.IGCOptions;
 
@@ -2905,7 +2906,7 @@ olx.source.IGCOptions.prototype.urls;
  *     ratio: (number|undefined),
  *     resolutions: (Array.<number>|undefined),
  *     params: (Object|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.MapGuideOptions;
 
@@ -2993,7 +2994,7 @@ olx.source.MapGuideOptions.prototype.params;
  *     text: (string|undefined),
  *     url: (string|undefined),
  *     urls: (Array.<string>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.KMLOptions;
 
@@ -3072,7 +3073,7 @@ olx.source.KMLOptions.prototype.urls;
 /**
  * @typedef {{layer: string,
  *     tileLoadFunction: (ol.TileLoadFunctionType|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.MapQuestOptions;
 
@@ -3095,7 +3096,7 @@ olx.source.MapQuestOptions.prototype.tileLoadFunction;
  * @typedef {{extent: (ol.Extent|undefined),
  *     projection: ol.proj.ProjectionLike,
  *     tileGrid: (ol.tilegrid.TileGrid|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.TileDebugOptions;
 
@@ -3127,7 +3128,7 @@ olx.source.TileDebugOptions.prototype.tileGrid;
  *     maxZoom: (number|undefined),
  *     tileLoadFunction: (ol.TileLoadFunctionType|undefined),
  *     url: (string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.OSMOptions;
 
@@ -3180,7 +3181,7 @@ olx.source.OSMOptions.prototype.url;
  *     text: (string|undefined),
  *     url: (string|undefined),
  *     urls: (Array.<string>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.OSMXMLOptions;
 
@@ -3271,7 +3272,7 @@ olx.source.OSMXMLOptions.prototype.urls;
  *     ratio: (number|undefined),
  *     resolutions: (Array.<number>|undefined),
  *     state: (ol.source.State|string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.ImageCanvasOptions;
 
@@ -3350,7 +3351,7 @@ olx.source.ImageCanvasOptions.prototype.state;
  *     resolutions: (Array.<number>|undefined),
  *     source: ol.source.Vector,
  *     style: (ol.style.Style|Array.<ol.style.Style>|ol.feature.StyleFunction|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.ImageVectorOptions;
 
@@ -3426,7 +3427,7 @@ olx.source.ImageVectorOptions.prototype.style;
  *     ratio: (number|undefined),
  *     resolutions: (Array.<number>|undefined),
  *     url: (string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.ImageWMSOptions;
 
@@ -3520,7 +3521,7 @@ olx.source.ImageWMSOptions.prototype.url;
  *     opaque: (boolean|undefined),
  *     tileLoadFunction: (ol.TileLoadFunctionType|undefined),
  *     url: (string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.StamenOptions;
 
@@ -3576,7 +3577,7 @@ olx.source.StamenOptions.prototype.url;
  *     logo: (string|undefined),
  *     projection: ol.proj.ProjectionLike,
  *     url: string}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.ImageStaticOptions;
 
@@ -3645,7 +3646,7 @@ olx.source.ImageStaticOptions.prototype.url;
  *     strategy: (function(ol.Extent, number): Array.<ol.Extent>|undefined),
  *     logo: (string|undefined),
  *     projection: ol.proj.ProjectionLike}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.ServerVectorOptions;
 
@@ -3703,7 +3704,7 @@ olx.source.ServerVectorOptions.prototype.projection;
  * @typedef {{crossOrigin: (null|string|undefined),
  *     tileLoadFunction: (ol.TileLoadFunctionType|undefined),
  *     url: string}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.TileJSONOptions;
 
@@ -3744,7 +3745,7 @@ olx.source.TileJSONOptions.prototype.url;
  *     tileLoadFunction: (ol.TileLoadFunctionType|undefined),
  *     url: (string|undefined),
  *     urls: (Array.<string>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.TileWMSOptions;
 
@@ -3866,7 +3867,7 @@ olx.source.TileWMSOptions.prototype.urls;
  *     logo: (string|undefined),
  *     projection: ol.proj.ProjectionLike,
  *     state: (ol.source.State|string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.VectorOptions;
 
@@ -3926,7 +3927,7 @@ olx.source.VectorOptions.prototype.state;
  *     text: (string|undefined),
  *     url: (string|undefined),
  *     urls: (Array.<string>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.StaticVectorOptions;
 
@@ -4033,7 +4034,7 @@ olx.source.StaticVectorOptions.prototype.urls;
  *     maxZoom: (number|undefined),
  *     tileLoadFunction: (ol.TileLoadFunctionType|undefined),
  *     urls: (Array.<string>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.WMTSOptions;
 
@@ -4170,7 +4171,7 @@ olx.source.WMTSOptions.prototype.urls;
  *     url: (string|undefined),
  *     urls: (Array.<string>|undefined),
  *     wrapX: (boolean|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.XYZOptions;
 
@@ -4267,7 +4268,7 @@ olx.source.XYZOptions.prototype.wrapX;
  *     url: !string,
  *     tierSizeCalculation: (string|undefined),
  *     size: ol.Size}}
- * @todo stability experimental
+ * @todo api
  */
 olx.source.ZoomifyOptions;
 
@@ -4318,7 +4319,7 @@ olx.source.ZoomifyOptions.prototype.size;
  * @typedef {{fill: (ol.style.Fill|undefined),
  *     radius: number,
  *     stroke: (ol.style.Stroke|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.style.CircleOptions;
 
@@ -4346,7 +4347,7 @@ olx.style.CircleOptions.prototype.stroke;
 
 /**
  * @typedef {{color: (ol.Color|string|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.style.FillOptions;
 
@@ -4369,7 +4370,7 @@ olx.style.FillOptions.prototype.color;
  *     rotation: (number|undefined),
  *     size: (ol.Size|undefined),
  *     src: string}}
- * @todo stability experimental
+ * @todo api
  */
 olx.style.IconOptions;
 
@@ -4456,7 +4457,7 @@ olx.style.IconOptions.prototype.src;
  *     lineDash: (Array.<number>|undefined),
  *     miterLimit: (number|undefined),
  *     width: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.style.StrokeOptions;
 
@@ -4514,7 +4515,7 @@ olx.style.StrokeOptions.prototype.width;
  *     textBaseline: (string|undefined),
  *     fill: (ol.style.Fill|undefined),
  *     stroke: (ol.style.Stroke|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.style.TextOptions;
 
@@ -4597,7 +4598,7 @@ olx.style.TextOptions.prototype.stroke;
  *     stroke: (ol.style.Stroke|undefined),
  *     text: (ol.style.Text|undefined),
  *     zIndex: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.style.StyleOptions;
 
@@ -4644,7 +4645,7 @@ olx.style.StyleOptions.prototype.zIndex;
  *     resolutions: !Array.<number>,
  *     tileSize: (number|undefined),
  *     tileSizes: (Array.<number>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.tilegrid.TileGridOptions;
 
@@ -4698,7 +4699,7 @@ olx.tilegrid.TileGridOptions.prototype.tileSizes;
  *     matrixIds: !Array.<string>,
  *     tileSize: (number|undefined),
  *     tileSizes: (Array.<number>|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.tilegrid.WMTSOptions;
 
@@ -4747,7 +4748,7 @@ olx.tilegrid.WMTSOptions.prototype.tileSizes;
 
 /**
  * @typedef {{maxZoom: number}}
- * @todo stability experimental
+ * @todo api
  */
 olx.tilegrid.XYZOptions;
 
@@ -4761,7 +4762,7 @@ olx.tilegrid.XYZOptions.prototype.maxZoom;
 
 /**
  * @typedef {{resolutions: !Array.<number>}}
- * @todo stability experimental
+ * @todo api
  */
 olx.tilegrid.ZoomifyOptions;
 
@@ -4778,7 +4779,7 @@ olx.tilegrid.ZoomifyOptions.prototype.resolutions;
  *     constrainResolution: (boolean|undefined),
  *     nearest: (boolean|undefined),
  *     minResolution: (number|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.View2D.fitGeometryOptions;
 

externs/readme.md

@@ -0,0 +1,116 @@
+# Externs
+
+This directory contains externs files, which tell the Closure compiler about symbols and properties that it should not rename.
+
+## oli.js and olx.js
+
+These two files are special externs that belong to ol3, and this document explains their purpose and how they are used.
+
+### Prevent class properties from being renamed
+
+For events, we make properties available to the application. Other than methods, which can be made available by just marking them with the `@api` annotation, properties are exported using `oli.js`:
+```js
+/** @interface */
+oli.MapBrowserEvent;
+
+/**
+ * @type {ol.Coordinate}
+ * @todo api
+ */
+oli.MapBrowserEvent.prototype.coordinate;
+```
+In the source file (`src/ol/MapBrowserEvent.js`), the class needs to implement this interface:
+```js
+/**
+ * ...
+ * @constructor
+ * @implements {oli.MapBrowserEvent}
+ */
+ol.MapBrowserEvent = function(type, map, browserEvent, opt_frameState) {
+
+  // ...
+
+  /**
+   * @type {ol.Coordinate}
+   */
+  this.coordinate = map.getEventCoordinate(this.originalEvent);
+
+  // ...
+
+};
+```
+
+### Override methods in custom classes
+
+For custom subclasses in applications, which can be created using `ol.extends`, the API may want to make certain methods available to override. In addition to marking such methods as `@api`, they need also be added to an interface in `oli.js`:
+```js
+/**
+ * @interface
+ */
+oli.control.Control;
+
+/**
+ * @param {ol.Map} map Map.
+ * @return {undefined} Undefined.
+ */
+oli.control.Control.prototype.setMap = function(map) {};
+
+```
+This interface must be implemented by the class in the source file (`src/ol/control/control.js`):
+```js
+/**
+ * ...
+ * @constructor
+ * @implements {oli.control.Control}
+ */
+ol.control.Control = function(options) {
+  // ...
+};
+
+// ...
+
+/**
+ * Application subclasses may override this.
+ * @param {ol.Map} map Map.
+ * @todo api
+ */
+ol.control.Control.prototype.setMap = function(map) {
+  // ...
+};
+```
+
+### Export object literals
+
+Object literals cannot be exported like classes. To make sure that their properties do not get renamed, they go in `olx.js`:
+```js
+/**
+ * @typedef {{element: (Element|undefined),
+ *     target: (Element|string|undefined)}}
+ * @todo api
+ */
+olx.control.ControlOptions;
+
+/**
+ * The element is the control's container element. This only needs to be
+ * specified if you're developing a custom control.
+ * @type {Element|undefined}
+ */
+olx.control.ControlOptions.prototype.element;
+
+/**
+ * Specify a target if you want the control to be rendered outside of the map's
+ * viewport.
+ * @type {Element|string|undefined}
+ */
+olx.control.ControlOptions.prototype.target;
+```
+In the source code, the name used for the typedef is used as type whenever this object literal is expected:
+```js
+/**
+ * ...
+ * @param {olx.control.ControlOptions} options Control options.
+ */
+ol.control.Control = function(options) {
+  // ...
+};
+```

old/src/ol/expr.exports

@@ -1,2 +0,0 @@
-@exportSymbol ol.expr.parse
-@exportSymbol ol.expr.register

old/src/ol/parser/ogc/versionedparser.exports

@@ -1 +0,0 @@
-@exportProperty ol.parser.ogc.Versioned.prototype.getParser

old/src/ol/parser/ogc/wmtscapabilitiesparser.exports

@@ -1,2 +0,0 @@
-@exportSymbol ol.parser.ogc.WMTSCapabilities
-@exportProperty ol.parser.ogc.WMTSCapabilities.prototype.read

old/src/ol/parser/wktparser.exports

@@ -1,5 +0,0 @@
-@exportSymbol ol.parser.WKT
-@exportProperty ol.parser.WKT.prototype.read
-@exportProperty ol.parser.WKT.prototype.write
-@exportProperty ol.parser.WKT.read
-@exportProperty ol.parser.WKT.write

old/src/ol/style.exports

@@ -1,9 +0,0 @@
-@exportSymbol ol.style.Fill
-@exportSymbol ol.style.Icon
-@exportSymbol ol.style.Rule
-@exportSymbol ol.style.Shape
-@exportSymbol ol.style.Stroke
-@exportSymbol ol.style.Style
-@exportSymbol ol.style.Text
-@exportSymbol ol.style.ShapeType
-@exportProperty ol.style.ShapeType.CIRCLE

package.json

@@ -15,10 +15,14 @@
     "url": "https://github.com/openlayers/ol3/issues"
   },
   "devDependencies": {
-    "closure-util": "~0.9.0",
+    "closure-util": "~0.11.0",
     "async": "~0.2.10",
     "htmlparser2": "~3.7.1",
     "jshint": "~2.4.4",
-    "jsdoc": "^3.3.0-alpha5"
+    "jsdoc": "~3.3.0-alpha5",
+    "walk": "~2.3.1",
+    "fs-extra": "~0.8.1",
+    "nomnom": "~1.6.2",
+    "temp": "~0.7.0"
   }
 }

src/ol/animation.exports

@@ -1,4 +0,0 @@
-@exportSymbol ol.animation.bounce
-@exportSymbol ol.animation.pan
-@exportSymbol ol.animation.rotate
-@exportSymbol ol.animation.zoom

src/ol/animation.js

@@ -11,7 +11,7 @@ goog.require('ol.easing');
 /**
  * @param {olx.animation.BounceOptions} options Bounce options.
  * @return {ol.PreRenderFunction} Pre-render function.
- * @todo stability experimental
+ * @todo api
  */
 ol.animation.bounce = function(options) {
   var resolution = options.resolution;
@@ -46,7 +46,7 @@ ol.animation.bounce = function(options) {
 /**
  * @param {olx.animation.PanOptions} options Pan options.
  * @return {ol.PreRenderFunction} Pre-render function.
- * @todo stability experimental
+ * @todo api
  */
 ol.animation.pan = function(options) {
   var source = options.source;
@@ -85,7 +85,7 @@ ol.animation.pan = function(options) {
 /**
  * @param {olx.animation.RotateOptions} options Rotate options.
  * @return {ol.PreRenderFunction} Pre-render function.
- * @todo stability experimental
+ * @todo api
  */
 ol.animation.rotate = function(options) {
   var sourceRotation = goog.isDef(options.rotation) ? options.rotation : 0;
@@ -130,7 +130,7 @@ ol.animation.rotate = function(options) {
 /**
  * @param {olx.animation.ZoomOptions} options Zoom options.
  * @return {ol.PreRenderFunction} Pre-render function.
- * @todo stability experimental
+ * @todo api
  */
 ol.animation.zoom = function(options) {
   var sourceResolution = options.resolution;

src/ol/attribution.exports

@@ -1 +0,0 @@
-@exportSymbol ol.Attribution

src/ol/attribution.js

@@ -22,7 +22,7 @@ goog.require('ol.TileRange');
  * @constructor
  * @param {olx.AttributionOptions} options Attribution options.
  * @struct
- * @todo stability experimental
+ * @todo api
  */
 ol.Attribution = function(options) {
 

src/ol/browserfeature.exports

@@ -1,7 +0,0 @@
-@exportSymbol ol.BrowserFeature
-@exportProperty ol.BrowserFeature.DEVICE_PIXEL_RATIO
-@exportProperty ol.BrowserFeature.HAS_CANVAS
-@exportProperty ol.BrowserFeature.HAS_DEVICE_ORIENTATION
-@exportProperty ol.BrowserFeature.HAS_GEOLOCATION
-@exportProperty ol.BrowserFeature.HAS_TOUCH
-@exportProperty ol.BrowserFeature.HAS_WEBGL

src/ol/browserfeature.js

@@ -77,7 +77,7 @@ ol.IS_LEGACY_IE = goog.userAgent.IE &&
  * (dips) on the device (`window.devicePixelRatio`).
  * @const
  * @type {number}
- * @todo stability experimental
+ * @todo api
  */
 ol.BrowserFeature.DEVICE_PIXEL_RATIO = goog.global.devicePixelRatio || 1;
 
@@ -86,7 +86,6 @@ ol.BrowserFeature.DEVICE_PIXEL_RATIO = goog.global.devicePixelRatio || 1;
  * True if the browser supports ArrayBuffers.
  * @const
  * @type {boolean}
- * @todo stability experimental
  */
 ol.BrowserFeature.HAS_ARRAY_BUFFER = 'ArrayBuffer' in goog.global;
 
@@ -94,7 +93,6 @@ ol.BrowserFeature.HAS_ARRAY_BUFFER = 'ArrayBuffer' in goog.global;
 /**
  * True if the browser's Canvas implementation implements {get,set}LineDash.
  * @type {boolean}
- * @todo stability experimental
  */
 ol.BrowserFeature.HAS_CANVAS_LINE_DASH = false;
 
@@ -103,7 +101,7 @@ ol.BrowserFeature.HAS_CANVAS_LINE_DASH = false;
  * True if browser supports Canvas.
  * @const
  * @type {boolean}
- * @todo stability experimental
+ * @todo api
  */
 ol.BrowserFeature.HAS_CANVAS = ol.ENABLE_CANVAS && (
     /**
@@ -133,7 +131,7 @@ ol.BrowserFeature.HAS_CANVAS = ol.ENABLE_CANVAS && (
  * Indicates if DeviceOrientation is supported in the user's browser.
  * @const
  * @type {boolean}
- * @todo stability experimental
+ * @todo api
  */
 ol.BrowserFeature.HAS_DEVICE_ORIENTATION =
     'DeviceOrientationEvent' in goog.global;
@@ -143,7 +141,6 @@ ol.BrowserFeature.HAS_DEVICE_ORIENTATION =
  * True if browser supports DOM.
  * @const
  * @type {boolean}
- * @todo stability experimental
  */
 ol.BrowserFeature.HAS_DOM = ol.ENABLE_DOM;
 
@@ -152,7 +149,7 @@ ol.BrowserFeature.HAS_DOM = ol.ENABLE_DOM;
  * Is HTML5 geolocation supported in the current browser?
  * @const
  * @type {boolean}
- * @todo stability experimental
+ * @todo api
  */
 ol.BrowserFeature.HAS_GEOLOCATION = 'geolocation' in goog.global.navigator;
 
@@ -160,7 +157,6 @@ ol.BrowserFeature.HAS_GEOLOCATION = 'geolocation' in goog.global.navigator;
 /**
  * @const
  * @type {boolean}
- * @todo stability experimental
  */
 ol.BrowserFeature.HAS_JSON_PARSE =
     'JSON' in goog.global && 'parse' in goog.global.JSON;
@@ -170,7 +166,7 @@ ol.BrowserFeature.HAS_JSON_PARSE =
  * True if browser supports touch events.
  * @const
  * @type {boolean}
- * @todo stability experimental
+ * @todo api
  */
 ol.BrowserFeature.HAS_TOUCH = ol.ASSUME_TOUCH || 'ontouchstart' in goog.global;
 
@@ -179,7 +175,6 @@ ol.BrowserFeature.HAS_TOUCH = ol.ASSUME_TOUCH || 'ontouchstart' in goog.global;
  * True if browser supports pointer events.
  * @const
  * @type {boolean}
- * @todo stability experimental
  */
 ol.BrowserFeature.HAS_POINTER = 'PointerEvent' in goog.global;
 
@@ -188,7 +183,6 @@ ol.BrowserFeature.HAS_POINTER = 'PointerEvent' in goog.global;
  * True if browser supports ms pointer events (IE 10).
  * @const
  * @type {boolean}
- * @todo stability experimental
  */
 ol.BrowserFeature.HAS_MSPOINTER =
     !!(goog.global.navigator.msPointerEnabled);
@@ -198,7 +192,6 @@ ol.BrowserFeature.HAS_MSPOINTER =
  * True if browser supports WebGL.
  * @const
  * @type {boolean}
- * @todo stability experimental
  */
 ol.BrowserFeature.HAS_WEBGL = ol.ENABLE_WEBGL && (
     /**

src/ol/canvasfunction.js

@@ -12,6 +12,6 @@ goog.provide('ol.CanvasFunctionType');
  *
  * @typedef {function(this:ol.source.ImageCanvas, ol.Extent, number,
  *     number, ol.Size, ol.proj.Projection): HTMLCanvasElement}
- * @todo stability experimental
+ * @todo api
  */
 ol.CanvasFunctionType;

src/ol/centerconstraint.js

@@ -6,7 +6,7 @@ goog.require('goog.math');
 
 /**
  * @typedef {function((ol.Coordinate|undefined)): (ol.Coordinate|undefined)}
- * @todo stability experimental
+ * @todo api
  */
 ol.CenterConstraintType;
 

src/ol/collection.exports

@@ -1,13 +0,0 @@
-@exportSymbol ol.Collection
-@exportProperty ol.Collection.prototype.clear
-@exportProperty ol.Collection.prototype.extend
-@exportProperty ol.Collection.prototype.forEach
-@exportProperty ol.Collection.prototype.getArray
-@exportProperty ol.Collection.prototype.getAt
-@exportProperty ol.Collection.prototype.getLength
-@exportProperty ol.Collection.prototype.insertAt
-@exportProperty ol.Collection.prototype.pop
-@exportProperty ol.Collection.prototype.push
-@exportProperty ol.Collection.prototype.remove
-@exportProperty ol.Collection.prototype.removeAt
-@exportProperty ol.Collection.prototype.setAt

src/ol/collection.js

@@ -19,13 +19,13 @@ ol.CollectionEventType = {
   /**
    * Triggered when an item is added to the collection.
    * @event ol.CollectionEvent#add
-   * @todo stability experimental
+   * @todo api
    */
   ADD: 'add',
   /**
    * Triggered when an item is removed from the collection.
    * @event ol.CollectionEvent#remove
-   * @todo stability experimental
+   * @todo api
    */
   REMOVE: 'remove'
 };
@@ -47,7 +47,6 @@ ol.CollectionEvent = function(type, opt_element, opt_target) {
   /**
    * The element that is added to or removed from the collection.
    * @type {*}
-   * @todo stability experimental
    */
   this.element = opt_element;
 
@@ -70,8 +69,8 @@ ol.CollectionProperty = {
  * @extends {ol.Object}
  * @fires {@link ol.CollectionEvent} ol.CollectionEvent
  * @param {Array=} opt_array Array.
- * @todo stability experimental
  * @todo observable length {number} readonly the length of the array
+ * @todo api
  */
 ol.Collection = function(opt_array) {
 
@@ -91,7 +90,7 @@ goog.inherits(ol.Collection, ol.Object);
 
 /**
  * Remove all elements from the collection.
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.clear = function() {
   while (this.getLength() > 0) {
@@ -103,7 +102,7 @@ ol.Collection.prototype.clear = function() {
 /**
  * @param {Array} arr Array.
  * @return {ol.Collection} This collection.
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.extend = function(arr) {
   var i, ii;
@@ -121,7 +120,7 @@ ol.Collection.prototype.extend = function(arr) {
  *     index and the array). The return value is ignored.
  * @param {S=} opt_this The object to use as `this` in `f`.
  * @template T,S
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.forEach = function(f, opt_this) {
   goog.array.forEach(this.array_, f, opt_this);
@@ -134,7 +133,7 @@ ol.Collection.prototype.forEach = function(f, opt_this) {
  * collection's "length" property won't be in sync with the actual length
  * of the array.
  * @return {Array} Array.
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.getArray = function() {
   return this.array_;
@@ -145,7 +144,7 @@ ol.Collection.prototype.getArray = function() {
  * Get the element at the provided index.
  * @param {number} index Index.
  * @return {*} Element.
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.getAt = function(index) {
   return this.array_[index];
@@ -155,7 +154,7 @@ ol.Collection.prototype.getAt = function(index) {
 /**
  * Get the length of this collection.
  * @return {number} Length.
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.getLength = function() {
   return /** @type {number} */ (this.get(ol.CollectionProperty.LENGTH));
@@ -166,7 +165,7 @@ ol.Collection.prototype.getLength = function() {
  * Insert an element at the provided index.
  * @param {number} index Index.
  * @param {*} elem Element.
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.insertAt = function(index, elem) {
   goog.array.insertAt(this.array_, elem, index);
@@ -179,7 +178,7 @@ ol.Collection.prototype.insertAt = function(index, elem) {
 /**
  * Remove the last element of the collection.
  * @return {*} Element.
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.pop = function() {
   return this.removeAt(this.getLength() - 1);
@@ -190,7 +189,7 @@ ol.Collection.prototype.pop = function() {
  * Insert the provided element at the end of the collection.
  * @param {*} elem Element.
  * @return {number} Length.
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.push = function(elem) {
   var n = this.array_.length;
@@ -203,7 +202,7 @@ ol.Collection.prototype.push = function(elem) {
  * Removes the first occurence of elem from the collection.
  * @param {*} elem Element.
  * @return {*} The removed element or undefined if elem was not found.
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.remove = function(elem) {
   var arr = this.array_;
@@ -221,7 +220,7 @@ ol.Collection.prototype.remove = function(elem) {
  * Remove the element at the provided index.
  * @param {number} index Index.
  * @return {*} Value.
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.removeAt = function(index) {
   var prev = this.array_[index];
@@ -237,7 +236,7 @@ ol.Collection.prototype.removeAt = function(index) {
  * Set the element at the provided index.
  * @param {number} index Index.
  * @param {*} elem Element.
- * @todo stability experimental
+ * @todo api
  */
 ol.Collection.prototype.setAt = function(index, elem) {
   var n = this.getLength();

src/ol/color/color.exports

@@ -1,2 +0,0 @@
-@exportSymbol ol.color.asArray
-@exportSymbol ol.color.asString

src/ol/color/color.js

@@ -103,6 +103,7 @@ ol.color.blend = function(dst, src, opt_color) {
 /**
  * @param {ol.Color|string} color Color.
  * @return {ol.Color} Color.
+ * @todo api
  */
 ol.color.asArray = function(color) {
   if (goog.isArray(color)) {
@@ -117,6 +118,7 @@ ol.color.asArray = function(color) {
 /**
  * @param {ol.Color|string} color Color.
  * @return {string} String.
+ * @todo api
  */
 ol.color.asString = function(color) {
   if (goog.isString(color)) {

src/ol/control/attributioncontrol.exports

@@ -1,2 +0,0 @@
-@exportSymbol ol.control.Attribution
-@exportProperty ol.control.Attribution.prototype.setMap

src/ol/control/attributioncontrol.js

@@ -21,7 +21,7 @@ goog.require('ol.css');
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.AttributionOptions=} opt_options Attribution options.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.Attribution = function(opt_options) {
 

src/ol/control/control.exports

@@ -1,3 +0,0 @@
-@exportSymbol ol.control.Control
-@exportProperty ol.control.Control.prototype.getMap
-@exportProperty ol.control.Control.prototype.setMap

src/ol/control/control.js

@@ -16,7 +16,7 @@ goog.require('ol.Object');
  * @extends {ol.Object}
  * @implements {oli.control.Control}
  * @param {olx.control.ControlOptions} options Control options.
- * @todo stability stable
+ * @todo api stable
  */
 ol.control.Control = function(options) {
 
@@ -63,7 +63,7 @@ ol.control.Control.prototype.disposeInternal = function() {
 /**
  * Get the map associated with this control.
  * @return {ol.Map} Map.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.Control.prototype.getMap = function() {
   return this.map_;
@@ -84,7 +84,7 @@ ol.control.Control.prototype.handleMapPostrender = goog.nullFunction;
  * Subclasses may set up event handlers to get notified about changes to
  * the map here.
  * @param {ol.Map} map Map.
- * @todo stability stable
+ * @todo api stable
  */
 ol.control.Control.prototype.setMap = function(map) {
   if (!goog.isNull(this.map_)) {

src/ol/control/controldefaults.exports

@@ -1 +0,0 @@
-@exportSymbol ol.control.defaults

src/ol/control/controldefaults.js

@@ -9,7 +9,7 @@ goog.require('ol.control.Zoom');
 /**
  * @param {olx.control.DefaultsOptions=} opt_options Defaults options.
  * @return {ol.Collection} Controls.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.defaults = function(opt_options) {
 

src/ol/control/fullscreencontrol.exports

@@ -1 +0,0 @@
-@exportSymbol ol.control.FullScreen

src/ol/control/fullscreencontrol.js

@@ -24,7 +24,7 @@ goog.require('ol.pointer.PointerEventHandler');
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.FullScreenOptions=} opt_options Options.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.FullScreen = function(opt_options) {
 

src/ol/control/logocontrol.exports

@@ -1,2 +0,0 @@
-@exportSymbol ol.control.Logo
-@exportProperty ol.control.Logo.prototype.setMap

src/ol/control/logocontrol.js

@@ -17,7 +17,7 @@ goog.require('ol.css');
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.LogoOptions=} opt_options Logo options.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.Logo = function(opt_options) {
 

src/ol/control/mousepositioncontrol.exports

@@ -1,2 +0,0 @@
-@exportSymbol ol.control.MousePosition
-@exportProperty ol.control.MousePosition.prototype.setMap

src/ol/control/mousepositioncontrol.js

@@ -38,11 +38,11 @@ ol.control.MousePositionProperty = {
  * @extends {ol.control.Control}
  * @param {olx.control.MousePositionOptions=} opt_options Mouse position
  *     options.
- * @todo stability experimental
  * @todo observable projection {ol.proj.Projection} the projection to report
  *       mouse position in
  * @todo observable coordinateFormat {ol.CoordinateFormatType} the format to
  *       render the current position in
+ * @todo api
  */
 ol.control.MousePosition = function(opt_options) {
 
@@ -132,8 +132,8 @@ ol.control.MousePosition.prototype.handleProjectionChanged_ = function() {
 
 
 /**
- * @return {ol.CoordinateFormatType|undefined} projection.
- * @todo stability experimental
+ * @return {ol.CoordinateFormatType|undefined} Coordinate format.
+ * @todo api
  */
 ol.control.MousePosition.prototype.getCoordinateFormat = function() {
   return /** @type {ol.CoordinateFormatType|undefined} */ (
@@ -146,8 +146,8 @@ goog.exportProperty(
 
 
 /**
- * @return {ol.proj.Projection|undefined} projection.
- * @todo stability experimental
+ * @return {ol.proj.Projection|undefined} Projection.
+ * @todo api
  */
 ol.control.MousePosition.prototype.getProjection = function() {
   return /** @type {ol.proj.Projection|undefined} */ (
@@ -184,6 +184,7 @@ ol.control.MousePosition.prototype.handleMouseOut = function(browserEvent) {
 
 /**
  * @inheritDoc
+ * @todo api
  */
 ol.control.MousePosition.prototype.setMap = function(map) {
   goog.base(this, 'setMap', map);
@@ -201,7 +202,7 @@ ol.control.MousePosition.prototype.setMap = function(map) {
 
 /**
  * @param {ol.CoordinateFormatType} format Coordinate format.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.MousePosition.prototype.setCoordinateFormat = function(format) {
   this.set(ol.control.MousePositionProperty.COORDINATE_FORMAT, format);
@@ -214,7 +215,7 @@ goog.exportProperty(
 
 /**
  * @param {ol.proj.Projection} projection Projection.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.MousePosition.prototype.setProjection = function(projection) {
   this.set(ol.control.MousePositionProperty.PROJECTION, projection);

src/ol/control/scalelinecontrol.exports

@@ -1,2 +0,0 @@
-@exportSymbol ol.control.ScaleLine
-@exportProperty ol.control.ScaleLine.prototype.setMap

src/ol/control/scalelinecontrol.js

@@ -20,7 +20,6 @@ goog.require('ol.sphere.NORMAL');
 
 /**
  * @enum {string}
- * @todo stability experimental
  */
 ol.control.ScaleLineProperty = {
   UNITS: 'units'
@@ -28,8 +27,10 @@ ol.control.ScaleLineProperty = {
 
 
 /**
+ * Units for the scale line. Supported values are `'degrees'`, `'imperial'`,
+ * `'nautical'`, `'metric'`, `'us'`.
  * @enum {string}
- * @todo stability experimental
+ * @todo api
  */
 ol.control.ScaleLineUnits = {
   DEGREES: 'degrees',
@@ -49,9 +50,9 @@ ol.control.ScaleLineUnits = {
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.ScaleLineOptions=} opt_options Scale line options.
- * @todo stability experimental
  * @todo observable units {ol.control.ScaleLineUnits} the units to use in the
  *       scale line
+ * @todo api
  */
 ol.control.ScaleLine = function(opt_options) {
 
@@ -131,14 +132,13 @@ goog.inherits(ol.control.ScaleLine, ol.control.Control);
 /**
  * @const
  * @type {Array.<number>}
- * @todo stability experimental
  */
 ol.control.ScaleLine.LEADING_DIGITS = [1, 2, 5];
 
 
 /**
  * @return {ol.control.ScaleLineUnits|undefined} units.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.ScaleLine.prototype.getUnits = function() {
   return /** @type {ol.control.ScaleLineUnits|undefined} */ (
@@ -174,7 +174,7 @@ ol.control.ScaleLine.prototype.handleUnitsChanged_ = function() {
 
 /**
  * @param {ol.control.ScaleLineUnits} units Units.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.ScaleLine.prototype.setUnits = function(units) {
   this.set(ol.control.ScaleLineProperty.UNITS, units);

src/ol/control/zoomcontrol.exports

@@ -1,2 +0,0 @@
-@exportSymbol ol.control.Zoom
-@exportProperty ol.control.Zoom.prototype.setMap

src/ol/control/zoomcontrol.js

@@ -23,7 +23,7 @@ goog.require('ol.pointer.PointerEventHandler');
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.ZoomOptions=} opt_options Zoom options.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.Zoom = function(opt_options) {
 

src/ol/control/zoomslidercontrol.exports

@@ -1 +0,0 @@
-@exportSymbol ol.control.ZoomSlider

src/ol/control/zoomslidercontrol.js

@@ -38,7 +38,7 @@ ol.control.ZOOMSLIDER_ANIMATION_DURATION = 200;
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.ZoomSliderOptions=} opt_options Zoom slider options.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.ZoomSlider = function(opt_options) {
 

src/ol/control/zoomtoextentcontrol.exports

@@ -1 +0,0 @@
-@exportSymbol ol.control.ZoomToExtent

src/ol/control/zoomtoextentcontrol.js

@@ -20,7 +20,7 @@ goog.require('ol.pointer.PointerEventHandler');
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.ZoomToExtentOptions=} opt_options Options.
- * @todo stability experimental
+ * @todo api
  */
 ol.control.ZoomToExtent = function(opt_options) {
   var options = goog.isDef(opt_options) ? opt_options : {};

src/ol/coordinate.exports

@@ -1,7 +0,0 @@
-@exportSymbol ol.coordinate.add
-@exportSymbol ol.coordinate.createStringXY
-@exportSymbol ol.coordinate.format
-@exportSymbol ol.coordinate.fromProjectedArray
-@exportSymbol ol.coordinate.rotate
-@exportSymbol ol.coordinate.toStringHDMS
-@exportSymbol ol.coordinate.toStringXY

src/ol/coordinate.js

@@ -11,7 +11,7 @@ goog.require('goog.math');
  * `{string}`.
  *
  * @typedef {function((ol.Coordinate|undefined)): string}
- * @todo stability experimental
+ * @todo api
  */
 ol.CoordinateFormatType;
 
@@ -19,7 +19,7 @@ ol.CoordinateFormatType;
 /**
  * An array of numbers representing a coordinate.
  * @typedef {Array.<number>} ol.Coordinate
- * @todo stability experimental
+ * @todo api
  */
 ol.Coordinate;
 
@@ -27,7 +27,7 @@ ol.Coordinate;
 /**
  * An array of coordinate arrays.
  * @typedef {Array.<ol.Coordinate>}
- * @todo stability experimental
+ * @todo api
  */
 ol.CoordinateArray;
 
@@ -36,6 +36,7 @@ ol.CoordinateArray;
  * @param {ol.Coordinate} coordinate Coordinate.
  * @param {ol.Coordinate} delta Delta.
  * @return {ol.Coordinate} Coordinate.
+ * @todo api
  */
 ol.coordinate.add = function(coordinate, delta) {
   coordinate[0] += delta[0];
@@ -87,7 +88,7 @@ ol.coordinate.closestOnSegment = function(coordinate, segment) {
  * @param {number=} opt_fractionDigits The number of digits to include
  *    after the decimal point. Default is `0`.
  * @return {ol.CoordinateFormatType} Coordinate format.
- * @todo stability experimental
+ * @todo api
  */
 ol.coordinate.createStringXY = function(opt_fractionDigits) {
   return (
@@ -124,7 +125,7 @@ ol.coordinate.degreesToStringHDMS_ = function(degrees, hemispheres) {
  * @param {number=} opt_fractionDigits The number of digits to include
  *    after the decimal point. Default is `0`.
  * @return {string} Formated coordinate.
- * @todo stability experimental
+ * @todo api
  */
 ol.coordinate.format = function(coordinate, template, opt_fractionDigits) {
   if (goog.isDef(coordinate)) {
@@ -158,6 +159,7 @@ ol.coordinate.equals = function(coordinate1, coordinate2) {
  * @param {ol.Coordinate} coordinate Coordinate.
  * @param {number} angle Angle.
  * @return {ol.Coordinate} Coordinate.
+ * @todo api
  */
 ol.coordinate.rotate = function(coordinate, angle) {
   var cosAngle = Math.cos(angle);
@@ -222,7 +224,7 @@ ol.coordinate.squaredDistanceToSegment = function(coordinate, segment) {
 /**
  * @param {ol.Coordinate|undefined} coordinate Coordinate.
  * @return {string} Hemisphere, degrees, minutes and seconds.
- * @todo stability experimental
+ * @todo api
  */
 ol.coordinate.toStringHDMS = function(coordinate) {
   if (goog.isDef(coordinate)) {
@@ -239,7 +241,7 @@ ol.coordinate.toStringHDMS = function(coordinate) {
  * @param {number=} opt_fractionDigits The number of digits to include
  *    after the decimal point. Default is `0`.
  * @return {string} XY.
- * @todo stability experimental
+ * @todo api
  */
 ol.coordinate.toStringXY = function(coordinate, opt_fractionDigits) {
   return ol.coordinate.format(coordinate, '{x}, {y}', opt_fractionDigits);
@@ -251,7 +253,7 @@ ol.coordinate.toStringXY = function(coordinate, opt_fractionDigits) {
  * @param {Array} array The array with coordinates.
  * @param {string} axis the axis info.
  * @return {ol.Coordinate} The coordinate created.
- * @todo stability experimental
+ * @todo api
  */
 ol.coordinate.fromProjectedArray = function(array, axis) {
   var firstAxis = axis.charAt(0);

src/ol/deviceorientation.exports

@@ -1 +0,0 @@
-@exportSymbol ol.DeviceOrientation

src/ol/deviceorientation.js

@@ -69,7 +69,6 @@ ol.DeviceOrientationProperty = {
  * @constructor
  * @extends {ol.Object}
  * @param {olx.DeviceOrientationOptions=} opt_options Options.
- * @todo stability experimental
  * @todo observable alpha {number} readonly the euler angle in radians of the
  *       device from the standard X axis
  * @todo observable beta {number} readonly the euler angle in radians of the
@@ -80,6 +79,7 @@ ol.DeviceOrientationProperty = {
  *       device from the planar Y axis
  * @todo observable tracking {boolean} the status of tracking changes to alpha,
  *       beta and gamma.  If true, changes are tracked and reported immediately.
+ * @todo api
  */
 ol.DeviceOrientation = function(opt_options) {
 
@@ -147,7 +147,7 @@ ol.DeviceOrientation.prototype.orientationChange_ = function(browserEvent) {
 /**
  * @return {number|undefined} The alpha value of the DeviceOrientation,
  * in radians.
- * @todo stability experimental
+ * @todo api
  */
 ol.DeviceOrientation.prototype.getAlpha = function() {
   return /** @type {number|undefined} */ (
@@ -162,7 +162,7 @@ goog.exportProperty(
 /**
  * @return {number|undefined} The beta value of the DeviceOrientation,
  * in radians.
- * @todo stability experimental
+ * @todo api
  */
 ol.DeviceOrientation.prototype.getBeta = function() {
   return /** @type {number|undefined} */ (
@@ -177,7 +177,7 @@ goog.exportProperty(
 /**
  * @return {number|undefined} The gamma value of the DeviceOrientation,
  * in radians.
- * @todo stability experimental
+ * @todo api
  */
 ol.DeviceOrientation.prototype.getGamma = function() {
   return /** @type {number|undefined} */ (
@@ -192,7 +192,7 @@ goog.exportProperty(
 /**
  * @return {number|undefined} The heading of the device relative to
  * north, in radians, normalizing for different browser behavior.
- * @todo stability experimental
+ * @todo api
  */
 ol.DeviceOrientation.prototype.getHeading = function() {
   return /** @type {number|undefined} */ (
@@ -207,7 +207,7 @@ goog.exportProperty(
 /**
  * Are we tracking the device's orientation?
  * @return {boolean} The current tracking state, true if tracking is on.
- * @todo stability experimental
+ * @todo api
  */
 ol.DeviceOrientation.prototype.getTracking = function() {
   return /** @type {boolean} */ (
@@ -239,7 +239,7 @@ ol.DeviceOrientation.prototype.handleTrackingChanged_ = function() {
 /**
  * Enable or disable tracking of DeviceOrientation events.
  * @param {boolean} tracking True to enable and false to disable tracking.
- * @todo stability experimental
+ * @todo api
  */
 ol.DeviceOrientation.prototype.setTracking = function(tracking) {
   this.set(ol.DeviceOrientationProperty.TRACKING, tracking);

src/ol/dom/input.exports

@@ -1 +0,0 @@
-@exportSymbol ol.dom.Input

src/ol/dom/input.js

@@ -29,9 +29,9 @@ ol.dom.InputProperty = {
  * @constructor
  * @extends {ol.Object}
  * @param {Element} target Target element.
- * @todo stability experimental
  * @todo observable value {string} the value of the Input
  * @todo observable checked {boolean} the checked state of the Input
+ * @todo api
  */
 ol.dom.Input = function(target) {
   goog.base(this);
@@ -59,7 +59,7 @@ goog.inherits(ol.dom.Input, ol.Object);
 /**
  * If the input is a checkbox, return whether or not the checbox is checked.
  * @return {boolean|undefined} checked.
- * @todo stability experimental
+ * @todo api
  */
 ol.dom.Input.prototype.getChecked = function() {
   return /** @type {boolean} */ (this.get(ol.dom.InputProperty.CHECKED));
@@ -73,7 +73,7 @@ goog.exportProperty(
 /**
  * Get the value of the input.
  * @return {string|undefined} input value.
- * @todo stability experimental
+ * @todo api
  */
 ol.dom.Input.prototype.getValue = function() {
   return /** @type {string} */ (this.get(ol.dom.InputProperty.VALUE));
@@ -87,7 +87,7 @@ goog.exportProperty(
 /**
  * Sets the value of the input.
  * @param {string} value Value.
- * @todo stability experimental
+ * @todo api
  */
 ol.dom.Input.prototype.setValue = function(value) {
   this.set(ol.dom.InputProperty.VALUE, value);
@@ -101,7 +101,7 @@ goog.exportProperty(
 /**
  * Set whether or not a checkbox is checked.
  * @param {boolean} checked Checked.
- * @todo stability experimental
+ * @todo api
  */
 ol.dom.Input.prototype.setChecked = function(checked) {
   this.set(ol.dom.InputProperty.CHECKED, checked);

src/ol/easing.exports

@@ -1,7 +0,0 @@
-@exportSymbol ol.easing.bounce
-@exportSymbol ol.easing.easeIn
-@exportSymbol ol.easing.easeOut
-@exportSymbol ol.easing.elastic
-@exportSymbol ol.easing.inAndOut
-@exportSymbol ol.easing.linear
-@exportSymbol ol.easing.upAndDown

src/ol/easing.js

@@ -7,6 +7,7 @@ goog.require('goog.fx.easing');
  * from https://raw.github.com/DmitryBaranovskiy/raphael/master/raphael.js
  * @param {number} t Input between 0 and 1.
  * @return {number} Output between 0 and 1.
+ * @todo api
  */
 ol.easing.bounce = function(t) {
   var s = 7.5625, p = 2.75, l;
@@ -33,6 +34,7 @@ ol.easing.bounce = function(t) {
 /**
  * @param {number} t Input between 0 and 1.
  * @return {number} Output between 0 and 1.
+ * @todo api
  */
 ol.easing.easeIn = goog.fx.easing.easeIn;
 
@@ -40,6 +42,7 @@ ol.easing.easeIn = goog.fx.easing.easeIn;
 /**
  * @param {number} t Input between 0 and 1.
  * @return {number} Output between 0 and 1.
+ * @todo api
  */
 ol.easing.easeOut = goog.fx.easing.easeOut;
 
@@ -48,6 +51,7 @@ ol.easing.easeOut = goog.fx.easing.easeOut;
  * from https://raw.github.com/DmitryBaranovskiy/raphael/master/raphael.js
  * @param {number} t Input between 0 and 1.
  * @return {number} Output between 0 and 1.
+ * @todo api
  */
 ol.easing.elastic = function(t) {
   return Math.pow(2, -10 * t) * Math.sin((t - 0.075) * (2 * Math.PI) / 0.3) + 1;
@@ -57,6 +61,7 @@ ol.easing.elastic = function(t) {
 /**
  * @param {number} t Input between 0 and 1.
  * @return {number} Output between 0 and 1.
+ * @todo api
  */
 ol.easing.inAndOut = goog.fx.easing.inAndOut;
 
@@ -64,6 +69,7 @@ ol.easing.inAndOut = goog.fx.easing.inAndOut;
 /**
  * @param {number} t Input between 0 and 1.
  * @return {number} Output between 0 and 1.
+ * @todo api
  */
 ol.easing.linear = function(t) {
   return t;
@@ -73,6 +79,7 @@ ol.easing.linear = function(t) {
 /**
  * @param {number} t Input between 0 and 1.
  * @return {number} Output between 0 and 1.
+ * @todo api
  */
 ol.easing.upAndDown = function(t) {
   if (t < 0.5) {

src/ol/events/condition.exports

@@ -1,8 +0,0 @@
-@exportSymbol ol.events.condition.altKeyOnly
-@exportSymbol ol.events.condition.altShiftKeysOnly
-@exportSymbol ol.events.condition.always
-@exportSymbol ol.events.condition.never
-@exportSymbol ol.events.condition.noModifierKeys
-@exportSymbol ol.events.condition.platformModifierKeyOnly
-@exportSymbol ol.events.condition.shiftKeyOnly
-@exportSymbol ol.events.condition.targetNotEditable

src/ol/events/condition.js

@@ -13,7 +13,7 @@ goog.require('ol.MapBrowserPointerEvent');
  * `{boolean}`. If the condition is met, true should be returned.
  *
  * @typedef {function(ol.MapBrowserEvent): boolean}
- * @todo stability experimental
+ * @todo api
  */
 ol.events.ConditionType;
 
@@ -21,7 +21,7 @@ ol.events.ConditionType;
 /**
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} True if only the alt key is pressed.
- * @todo stability experimental
+ * @todo api
  */
 ol.events.condition.altKeyOnly = function(mapBrowserEvent) {
   var browserEvent = mapBrowserEvent.browserEvent;
@@ -35,7 +35,7 @@ ol.events.condition.altKeyOnly = function(mapBrowserEvent) {
 /**
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} True if only the alt and shift keys are pressed.
- * @todo stability experimental
+ * @todo api
  */
 ol.events.condition.altShiftKeysOnly = function(mapBrowserEvent) {
   var browserEvent = mapBrowserEvent.browserEvent;
@@ -50,7 +50,7 @@ ol.events.condition.altShiftKeysOnly = function(mapBrowserEvent) {
  * Always true.
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} True.
- * @todo stability experimental
+ * @todo api
  */
 ol.events.condition.always = goog.functions.TRUE;
 
@@ -59,7 +59,7 @@ ol.events.condition.always = goog.functions.TRUE;
  * Always false.
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} False.
- * @todo stability experimental
+ * @todo api
  */
 ol.events.condition.never = goog.functions.FALSE;
 
@@ -67,7 +67,6 @@ ol.events.condition.never = goog.functions.FALSE;
 /**
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} True if the event is a `singleclick` event.
- * @todo stability experimental
  */
 ol.events.condition.singleClick = function(mapBrowserEvent) {
   return mapBrowserEvent.type == ol.MapBrowserEvent.EventType.SINGLECLICK;
@@ -77,7 +76,7 @@ ol.events.condition.singleClick = function(mapBrowserEvent) {
 /**
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} True only if there no modifier keys are pressed.
- * @todo stability experimental
+ * @todo api
  */
 ol.events.condition.noModifierKeys = function(mapBrowserEvent) {
   var browserEvent = mapBrowserEvent.browserEvent;
@@ -91,7 +90,7 @@ ol.events.condition.noModifierKeys = function(mapBrowserEvent) {
 /**
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} True if only the platform modifier key is pressed.
- * @todo stability experimental
+ * @todo api
  */
 ol.events.condition.platformModifierKeyOnly = function(mapBrowserEvent) {
   var browserEvent = mapBrowserEvent.browserEvent;
@@ -105,7 +104,7 @@ ol.events.condition.platformModifierKeyOnly = function(mapBrowserEvent) {
 /**
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} True if only the shift key is pressed.
- * @todo stability experimental
+ * @todo api
  */
 ol.events.condition.shiftKeyOnly = function(mapBrowserEvent) {
   var browserEvent = mapBrowserEvent.browserEvent;
@@ -119,7 +118,7 @@ ol.events.condition.shiftKeyOnly = function(mapBrowserEvent) {
 /**
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} True only if the target element is not editable.
- * @todo stability experimental
+ * @todo api
  */
 ol.events.condition.targetNotEditable = function(mapBrowserEvent) {
   var target = mapBrowserEvent.browserEvent.target;
@@ -135,7 +134,6 @@ ol.events.condition.targetNotEditable = function(mapBrowserEvent) {
 /**
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} True if the event originates from a mouse device.
- * @todo stability experimental
  */
 ol.events.condition.mouseOnly = function(mapBrowserEvent) {
   goog.asserts.assertInstanceof(mapBrowserEvent, ol.MapBrowserPointerEvent);

src/ol/extent.exports

@@ -1,18 +0,0 @@
-@exportSymbol ol.extent.boundingExtent
-@exportSymbol ol.extent.buffer
-@exportSymbol ol.extent.containsCoordinate
-@exportSymbol ol.extent.containsExtent
-@exportSymbol ol.extent.createEmpty
-@exportSymbol ol.extent.equals
-@exportSymbol ol.extent.extend
-@exportSymbol ol.extent.getBottomLeft
-@exportSymbol ol.extent.getBottomRight
-@exportSymbol ol.extent.getCenter
-@exportSymbol ol.extent.getHeight
-@exportSymbol ol.extent.getSize
-@exportSymbol ol.extent.getTopLeft
-@exportSymbol ol.extent.getTopRight
-@exportSymbol ol.extent.getWidth
-@exportSymbol ol.extent.intersects
-@exportSymbol ol.extent.isEmpty
-@exportSymbol ol.extent.transform

src/ol/extent.js

@@ -12,7 +12,7 @@ goog.require('ol.TransformFunction');
 /**
  * An array of numbers representing an extent: `[minx, miny, maxx, maxy]`.
  * @typedef {Array.<number>}
- * @todo stability experimental
+ * @todo api
  */
 ol.Extent;
 
@@ -36,7 +36,7 @@ ol.extent.Relationship = {
  *
  * @param {Array.<ol.Coordinate>} coordinates Coordinates.
  * @return {ol.Extent} Bounding extent.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.boundingExtent = function(coordinates) {
   var extent = ol.extent.createEmpty();
@@ -53,7 +53,6 @@ ol.extent.boundingExtent = function(coordinates) {
  * @param {ol.Extent=} opt_extent Destination extent.
  * @private
  * @return {ol.Extent} Extent.
- * @todo stability experimental
  */
 ol.extent.boundingExtentXYs_ = function(xs, ys, opt_extent) {
   goog.asserts.assert(xs.length > 0);
@@ -72,6 +71,7 @@ ol.extent.boundingExtentXYs_ = function(xs, ys, opt_extent) {
  * @param {number} value The amount by wich the extent should be buffered.
  * @param {ol.Extent=} opt_extent Extent.
  * @return {ol.Extent} Extent.
+ * @todo api
  */
 ol.extent.buffer = function(extent, value, opt_extent) {
   if (goog.isDef(opt_extent)) {
@@ -97,7 +97,6 @@ ol.extent.buffer = function(extent, value, opt_extent) {
  * @param {ol.Extent} extent Extent to clone.
  * @param {ol.Extent=} opt_extent Extent.
  * @return {ol.Extent} The clone.
- * @todo stability experimental
  */
 ol.extent.clone = function(extent, opt_extent) {
   if (goog.isDef(opt_extent)) {
@@ -144,7 +143,7 @@ ol.extent.closestSquaredDistanceXY = function(extent, x, y) {
  * @param {ol.Extent} extent Extent.
  * @param {ol.Coordinate} coordinate Coordinate.
  * @return {boolean} Contains.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.containsCoordinate = function(extent, coordinate) {
   return extent[0] <= coordinate[0] && coordinate[0] <= extent[2] &&
@@ -158,7 +157,7 @@ ol.extent.containsCoordinate = function(extent, coordinate) {
  * @param {ol.Extent} extent1 Extent 1.
  * @param {ol.Extent} extent2 Extent 2.
  * @return {boolean} Contains.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.containsExtent = function(extent1, extent2) {
   return extent1[0] <= extent2[0] && extent2[2] <= extent1[2] &&
@@ -200,7 +199,7 @@ ol.extent.coordinateRelationship = function(extent, coordinate) {
 
 /**
  * @return {ol.Extent} Empty extent.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.createEmpty = function() {
   return [Infinity, Infinity, -Infinity, -Infinity];
@@ -214,7 +213,6 @@ ol.extent.createEmpty = function() {
  * @param {number} maxY Maximum Y.
  * @param {ol.Extent=} opt_extent Destination extent.
  * @return {ol.Extent} Extent.
- * @todo stability experimental
  */
 ol.extent.createOrUpdate = function(minX, minY, maxX, maxY, opt_extent) {
   if (goog.isDef(opt_extent)) {
@@ -293,7 +291,6 @@ ol.extent.createOrUpdateFromRings = function(rings, opt_extent) {
  * Empties extent in place.
  * @param {ol.Extent} extent Extent.
  * @return {ol.Extent} Extent.
- * @todo stability experimental
  */
 ol.extent.empty = function(extent) {
   extent[0] = extent[1] = Infinity;
@@ -306,7 +303,7 @@ ol.extent.empty = function(extent) {
  * @param {ol.Extent} extent1 Extent 1.
  * @param {ol.Extent} extent2 Extent 2.
  * @return {boolean} Equals.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.equals = function(extent1, extent2) {
   return extent1[0] == extent2[0] && extent1[2] == extent2[2] &&
@@ -318,7 +315,7 @@ ol.extent.equals = function(extent1, extent2) {
  * @param {ol.Extent} extent1 Extent 1.
  * @param {ol.Extent} extent2 Extent 2.
  * @return {ol.Extent} Extent.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.extend = function(extent1, extent2) {
   if (extent2[0] < extent1[0]) {
@@ -340,7 +337,6 @@ ol.extent.extend = function(extent1, extent2) {
 /**
  * @param {ol.Extent} extent Extent.
  * @param {ol.Coordinate} coordinate Coordinate.
- * @todo stability experimental
  */
 ol.extent.extendCoordinate = function(extent, coordinate) {
   if (coordinate[0] < extent[0]) {
@@ -429,7 +425,7 @@ ol.extent.getArea = function(extent) {
 /**
  * @param {ol.Extent} extent Extent.
  * @return {ol.Coordinate} Bottom left coordinate.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.getBottomLeft = function(extent) {
   return [extent[0], extent[1]];
@@ -439,7 +435,7 @@ ol.extent.getBottomLeft = function(extent) {
 /**
  * @param {ol.Extent} extent Extent.
  * @return {ol.Coordinate} Bottom right coordinate.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.getBottomRight = function(extent) {
   return [extent[2], extent[1]];
@@ -449,7 +445,7 @@ ol.extent.getBottomRight = function(extent) {
 /**
  * @param {ol.Extent} extent Extent.
  * @return {ol.Coordinate} Center.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.getCenter = function(extent) {
   return [(extent[0] + extent[2]) / 2, (extent[1] + extent[3]) / 2];
@@ -477,7 +473,6 @@ ol.extent.getEnlargedArea = function(extent1, extent2) {
  * @param {ol.Size} size Size.
  * @param {ol.Extent=} opt_extent Destination extent.
  * @return {ol.Extent} Extent.
- * @todo stability experimental
  */
 ol.extent.getForView2DAndSize =
     function(center, resolution, rotation, size, opt_extent) {
@@ -503,7 +498,7 @@ ol.extent.getForView2DAndSize =
 /**
  * @param {ol.Extent} extent Extent.
  * @return {number} Height.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.getHeight = function(extent) {
   return extent[3] - extent[1];
@@ -536,7 +531,7 @@ ol.extent.getMargin = function(extent) {
 /**
  * @param {ol.Extent} extent Extent.
  * @return {ol.Size} Size.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.getSize = function(extent) {
   return [extent[2] - extent[0], extent[3] - extent[1]];
@@ -546,7 +541,7 @@ ol.extent.getSize = function(extent) {
 /**
  * @param {ol.Extent} extent Extent.
  * @return {ol.Coordinate} Top left coordinate.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.getTopLeft = function(extent) {
   return [extent[0], extent[3]];
@@ -556,7 +551,7 @@ ol.extent.getTopLeft = function(extent) {
 /**
  * @param {ol.Extent} extent Extent.
  * @return {ol.Coordinate} Top right coordinate.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.getTopRight = function(extent) {
   return [extent[2], extent[3]];
@@ -566,7 +561,7 @@ ol.extent.getTopRight = function(extent) {
 /**
  * @param {ol.Extent} extent Extent.
  * @return {number} Width.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.getWidth = function(extent) {
   return extent[2] - extent[0];
@@ -577,7 +572,7 @@ ol.extent.getWidth = function(extent) {
  * @param {ol.Extent} extent1 Extent 1.
  * @param {ol.Extent} extent2 Extent.
  * @return {boolean} Intersects.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.intersects = function(extent1, extent2) {
   return extent1[0] <= extent2[2] &&
@@ -590,7 +585,7 @@ ol.extent.intersects = function(extent1, extent2) {
 /**
  * @param {ol.Extent} extent Extent.
  * @return {boolean} Is empty.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.isEmpty = function(extent) {
   return extent[2] < extent[0] || extent[3] < extent[1];
@@ -600,7 +595,6 @@ ol.extent.isEmpty = function(extent) {
 /**
  * @param {ol.Extent} extent Extent.
  * @return {boolean} Is infinite.
- * @todo stability experimental
  */
 ol.extent.isInfinite = function(extent) {
   return extent[0] == -Infinity || extent[1] == -Infinity ||
@@ -612,7 +606,6 @@ ol.extent.isInfinite = function(extent) {
  * @param {ol.Extent} extent Extent.
  * @param {ol.Coordinate} coordinate Coordinate.
  * @return {ol.Coordinate} Coordinate.
- * @todo stability experimental
  */
 ol.extent.normalize = function(extent, coordinate) {
   return [
@@ -643,7 +636,6 @@ ol.extent.returnOrUpdate = function(extent, opt_extent) {
 /**
  * @param {ol.Extent} extent Extent.
  * @param {number} value Value.
- * @todo stability experimental
  */
 ol.extent.scaleFromCenter = function(extent, value) {
   var deltaX = ((extent[2] - extent[0]) / 2) * (value - 1);
@@ -712,7 +704,6 @@ ol.extent.segmentIntersects = function(extent, start, end) {
  * @param {ol.Extent} extent1 Extent 1.
  * @param {ol.Extent} extent2 Extent 2.
  * @return {boolean} Touches.
- * @todo stability experimental
  */
 ol.extent.touches = function(extent1, extent2) {
   var intersects = ol.extent.intersects(extent1, extent2);
@@ -727,7 +718,7 @@ ol.extent.touches = function(extent1, extent2) {
  * @param {ol.TransformFunction} transformFn Transform function.
  * @param {ol.Extent=} opt_extent Destination extent.
  * @return {ol.Extent} Extent.
- * @todo stability experimental
+ * @todo api
  */
 ol.extent.transform = function(extent, transformFn, opt_extent) {
   var coordinates = [

src/ol/feature.exports

@@ -1,8 +0,0 @@
-@exportSymbol ol.Feature
-@exportProperty ol.Feature.prototype.getGeometryName
-@exportProperty ol.Feature.prototype.getId
-@exportProperty ol.Feature.prototype.getStyle
-@exportProperty ol.Feature.prototype.getStyleFunction
-@exportProperty ol.Feature.prototype.setGeometryName
-@exportProperty ol.Feature.prototype.setId
-@exportProperty ol.Feature.prototype.setStyle

src/ol/feature.js

@@ -20,7 +20,7 @@ goog.require('ol.style.Style');
  * @extends {ol.Object}
  * @param {ol.geom.Geometry|Object.<string, *>=} opt_geometryOrValues
  *     Values or geometry.
- * @todo stability experimental
+ * @todo api
  */
 ol.Feature = function(opt_geometryOrValues) {
 
@@ -80,7 +80,7 @@ goog.inherits(ol.Feature, ol.Object);
 
 /**
  * @return {ol.geom.Geometry|undefined} Geometry.
- * @todo stability experimental
+ * @todo api
  */
 ol.Feature.prototype.getGeometry = function() {
   return /** @type {ol.geom.Geometry|undefined} */ (
@@ -94,7 +94,7 @@ goog.exportProperty(
 
 /**
  * @return {number|string|undefined} Id.
- * @todo stability experimental
+ * @todo api
  */
 ol.Feature.prototype.getId = function() {
   return this.id_;
@@ -103,7 +103,7 @@ ol.Feature.prototype.getId = function() {
 
 /**
  * @return {string} Geometry property name.
- * @todo stability experimental
+ * @todo api
  */
 ol.Feature.prototype.getGeometryName = function() {
   return this.geometryName_;
@@ -113,7 +113,7 @@ ol.Feature.prototype.getGeometryName = function() {
 /**
  * @return {ol.style.Style|Array.<ol.style.Style>|
  *     ol.feature.FeatureStyleFunction} User provided style.
- * @todo stability experimental
+ * @todo api
  */
 ol.Feature.prototype.getStyle = function() {
   return this.style_;
@@ -122,7 +122,7 @@ ol.Feature.prototype.getStyle = function() {
 
 /**
  * @return {ol.feature.FeatureStyleFunction|undefined} Style function.
- * @todo stability experimental
+ * @todo api
  */
 ol.Feature.prototype.getStyleFunction = function() {
   return this.styleFunction_;
@@ -156,7 +156,7 @@ ol.Feature.prototype.handleGeometryChanged_ = function() {
 
 /**
  * @param {ol.geom.Geometry|undefined} geometry Geometry.
- * @todo stability experimental
+ * @todo api
  */
 ol.Feature.prototype.setGeometry = function(geometry) {
   this.set(this.geometryName_, geometry);
@@ -170,7 +170,7 @@ goog.exportProperty(
 /**
  * @param {ol.style.Style|Array.<ol.style.Style>|
  *     ol.feature.FeatureStyleFunction} style Feature style.
- * @todo stability experimental
+ * @todo api
  */
 ol.Feature.prototype.setStyle = function(style) {
   this.style_ = style;
@@ -181,7 +181,7 @@ ol.Feature.prototype.setStyle = function(style) {
 
 /**
  * @param {number|string|undefined} id Id.
- * @todo stability experimental
+ * @todo api
  */
 ol.Feature.prototype.setId = function(id) {
   this.id_ = id;
@@ -190,7 +190,7 @@ ol.Feature.prototype.setId = function(id) {
 
 /**
  * @param {string} name Geometry property name.
- * @todo stability experimental
+ * @todo api
  */
 ol.Feature.prototype.setGeometryName = function(name) {
   goog.events.unlisten(
@@ -211,7 +211,7 @@ ol.Feature.prototype.setGeometryName = function(name) {
  * {@link ol.Feature} to be styled.
  *
  * @typedef {function(this: ol.Feature, number): Array.<ol.style.Style>}
- * @todo stability experimental
+ * @todo api
  */
 ol.feature.FeatureStyleFunction;
 
@@ -221,7 +221,6 @@ ol.feature.FeatureStyleFunction;
  * @param {number} resolution Resolution.
  * @return {Array.<ol.style.Style>} Style.
  * @this {ol.Feature}
- * @todo stability experimental
  */
 ol.feature.defaultFeatureStyleFunction = function(resolution) {
   var fill = new ol.style.Fill({
@@ -261,7 +260,7 @@ ol.feature.defaultFeatureStyleFunction = function(resolution) {
  * {@link ol.style.Style}. This way e.g. a vector layer can be styled.
  *
  * @typedef {function(ol.Feature, number): Array.<ol.style.Style>}
- * @todo stability experimental
+ * @todo api
  */
 ol.feature.StyleFunction;
 
@@ -270,7 +269,6 @@ ol.feature.StyleFunction;
  * @param {ol.Feature} feature Feature.
  * @param {number} resolution Resolution.
  * @return {Array.<ol.style.Style>} Style.
- * @todo stability experimental
  */
 ol.feature.defaultStyleFunction = function(feature, resolution) {
   var featureStyleFunction = feature.getStyleFunction();
@@ -351,7 +349,6 @@ ol.feature.createStyleFunction = function(obj) {
 /**
  * Default styles for editing features.
  * @return {Object.<ol.geom.GeometryType, Array.<ol.style.Style>>} Styles
- * @todo stability experimental
  */
 ol.feature.createDefaultEditingStyles = function() {
   /** @type {Object.<ol.geom.GeometryType, Array.<ol.style.Style>>} */

src/ol/featureoverlay.exports

@@ -1,9 +0,0 @@
-@exportSymbol ol.FeatureOverlay
-@exportProperty ol.FeatureOverlay.prototype.addFeature
-@exportProperty ol.FeatureOverlay.prototype.getFeatures
-@exportProperty ol.FeatureOverlay.prototype.getStyle
-@exportProperty ol.FeatureOverlay.prototype.getStyleFunction
-@exportProperty ol.FeatureOverlay.prototype.removeFeature
-@exportProperty ol.FeatureOverlay.prototype.setFeatures
-@exportProperty ol.FeatureOverlay.prototype.setMap
-@exportProperty ol.FeatureOverlay.prototype.setStyle

src/ol/featureoverlay.js

@@ -16,7 +16,7 @@ goog.require('ol.render.EventType');
 /**
  * @constructor
  * @param {olx.FeatureOverlayOptions=} opt_options Options.
- * @todo stability experimental
+ * @todo api
  */
 ol.FeatureOverlay = function(opt_options) {
 
@@ -85,7 +85,7 @@ ol.FeatureOverlay = function(opt_options) {
 
 /**
  * @param {ol.Feature} feature Feature.
- * @todo stability experimental
+ * @todo api
  */
 ol.FeatureOverlay.prototype.addFeature = function(feature) {
   this.features_.push(feature);
@@ -94,7 +94,7 @@ ol.FeatureOverlay.prototype.addFeature = function(feature) {
 
 /**
  * @return {ol.Collection} Features collection.
- * @todo stability experimental
+ * @todo api
  */
 ol.FeatureOverlay.prototype.getFeatures = function() {
   return this.features_;
@@ -167,7 +167,7 @@ ol.FeatureOverlay.prototype.handleMapPostCompose_ = function(event) {
 
 /**
  * @param {ol.Feature} feature Feature.
- * @todo stability experimental
+ * @todo api
  */
 ol.FeatureOverlay.prototype.removeFeature = function(feature) {
   this.features_.remove(feature);
@@ -186,7 +186,7 @@ ol.FeatureOverlay.prototype.render_ = function() {
 
 /**
  * @param {ol.Collection} features Features collection.
- * @todo stability experimental
+ * @todo api
  */
 ol.FeatureOverlay.prototype.setFeatures = function(features) {
   if (!goog.isNull(this.featuresListenerKeys_)) {
@@ -220,7 +220,7 @@ ol.FeatureOverlay.prototype.setFeatures = function(features) {
 
 /**
  * @param {ol.Map} map Map.
- * @todo stability experimental
+ * @todo api
  */
 ol.FeatureOverlay.prototype.setMap = function(map) {
   if (!goog.isNull(this.postComposeListenerKey_)) {
@@ -244,7 +244,7 @@ ol.FeatureOverlay.prototype.setMap = function(map) {
  * an array of styles.
  * @param {ol.style.Style|Array.<ol.style.Style>|ol.feature.StyleFunction} style
  *     Overlay style.
- * @todo stability experimental
+ * @todo api
  */
 ol.FeatureOverlay.prototype.setStyle = function(style) {
   this.style_ = style;
@@ -258,6 +258,7 @@ ol.FeatureOverlay.prototype.setStyle = function(style) {
  * option at construction or to the `setStyle` method.
  * @return {ol.style.Style|Array.<ol.style.Style>|ol.feature.StyleFunction}
  *     Overlay style.
+ * @todo api
  */
 ol.FeatureOverlay.prototype.getStyle = function() {
   return this.style_;
@@ -267,6 +268,7 @@ ol.FeatureOverlay.prototype.getStyle = function() {
 /**
  * Get the style function.
  * @return {ol.feature.StyleFunction|undefined} Style function.
+ * @todo api
  */
 ol.FeatureOverlay.prototype.getStyleFunction = function() {
   return this.styleFunction_;

src/ol/format/geojsonformat.exports

@@ -1,8 +0,0 @@
-@exportSymbol ol.format.GeoJSON
-@exportProperty ol.format.GeoJSON.prototype.readFeature
-@exportProperty ol.format.GeoJSON.prototype.readFeatures
-@exportProperty ol.format.GeoJSON.prototype.readGeometry
-@exportProperty ol.format.GeoJSON.prototype.readProjection
-@exportProperty ol.format.GeoJSON.prototype.writeFeature
-@exportProperty ol.format.GeoJSON.prototype.writeFeatures
-@exportProperty ol.format.GeoJSON.prototype.writeGeometry

src/ol/format/geojsonformat.js

@@ -26,7 +26,7 @@ goog.require('ol.proj');
  * @constructor
  * @extends {ol.format.JSONFeature}
  * @param {olx.format.GeoJSONOptions=} opt_options Options.
- * @todo stability experimental
+ * @todo api
  */
 ol.format.GeoJSON = function(opt_options) {
 
@@ -322,6 +322,7 @@ ol.format.GeoJSON.prototype.getExtensions = function() {
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {ol.Feature} Feature.
+ * @todo api
  */
 ol.format.GeoJSON.prototype.readFeature;
 
@@ -333,6 +334,7 @@ ol.format.GeoJSON.prototype.readFeature;
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {Array.<ol.Feature>} Features.
+ * @todo api
  */
 ol.format.GeoJSON.prototype.readFeatures;
 
@@ -386,6 +388,7 @@ ol.format.GeoJSON.prototype.readFeaturesFromObject = function(object) {
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {ol.geom.Geometry} Geometry.
+ * @todo api
  */
 ol.format.GeoJSON.prototype.readGeometry;
 
@@ -404,6 +407,7 @@ ol.format.GeoJSON.prototype.readGeometryFromObject = function(object) {
  *
  * @param {ArrayBuffer|Document|Node|Object|string} object Source.
  * @return {ol.proj.Projection} Projection.
+ * @todo api
  */
 ol.format.GeoJSON.prototype.readProjection = function(object) {
   var geoJSONObject = /** @type {GeoJSONObject} */ (object);
@@ -433,6 +437,7 @@ ol.format.GeoJSON.prototype.readProjection = function(object) {
  * @function
  * @param {ol.Feature} feature Feature.
  * @return {ArrayBuffer|Node|Object|string} Result.
+ * @todo api
  */
 ol.format.GeoJSON.prototype.writeFeature;
 
@@ -468,6 +473,7 @@ ol.format.GeoJSON.prototype.writeFeatureObject = function(feature) {
  * @function
  * @param {Array.<ol.Feature>} features Features.
  * @return {ArrayBuffer|Node|Object|string} Result.
+ * @todo api
  */
 ol.format.GeoJSON.prototype.writeFeatures;
 

src/ol/format/gmlformat.js

@@ -29,7 +29,6 @@ goog.require('ol.xml');
  * @param {olx.format.GMLOptions=} opt_options
  *     Optional configuration object.
  * @extends {ol.format.XMLFeature}
- * @todo stability experimental
  */
 ol.format.GML = function(opt_options) {
   var options = /** @type {olx.format.GMLOptions} */

src/ol/format/gpxformat.exports

@@ -1,5 +0,0 @@
-@exportSymbol ol.format.GPX
-@exportProperty ol.format.GPX.prototype.readFeature
-@exportProperty ol.format.GPX.prototype.readFeatures
-@exportProperty ol.format.GPX.prototype.readProjection
-@exportProperty ol.format.GPX.prototype.writeFeatures

src/ol/format/gpxformat.js

@@ -19,7 +19,7 @@ goog.require('ol.xml');
 /**
  * @constructor
  * @extends {ol.format.XMLFeature}
- * @todo stability experimental
+ * @todo api
  */
 ol.format.GPX = function() {
   goog.base(this);
@@ -369,6 +369,7 @@ ol.format.GPX.WPT_PARSERS_ = ol.xml.makeParsersNS(
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {ol.Feature} Feature.
+ * @todo api
  */
 ol.format.GPX.prototype.readFeature;
 
@@ -399,6 +400,7 @@ ol.format.GPX.prototype.readFeatureFromNode = function(node) {
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {Array.<ol.Feature>} Features.
+ * @todo api
  */
 ol.format.GPX.prototype.readFeatures;
 
@@ -430,6 +432,7 @@ ol.format.GPX.prototype.readFeaturesFromNode = function(node) {
  *
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {ol.proj.Projection} Projection.
+ * @todo api
  */
 ol.format.GPX.prototype.readProjection;
 
@@ -791,7 +794,6 @@ ol.format.GPX.GPX_SERIALIZERS_ = ol.xml.makeStructureNS(
 /**
  * @constructor
  * @extends {ol.format.GPX}
- * @todo stability experimental
  */
 ol.format.GPX.V1_1 = function() {
   goog.base(this);
@@ -805,6 +807,7 @@ goog.inherits(ol.format.GPX.V1_1, ol.format.GPX);
  * @function
  * @param {Array.<ol.Feature>} features Features.
  * @return {ArrayBuffer|Node|Object|string} Result.
+ * @todo api
  */
 ol.format.GPX.prototype.writeFeatures;
 

src/ol/format/igcformat.exports

@@ -1,4 +0,0 @@
-@exportSymbol ol.format.IGC
-@exportProperty ol.format.IGC.prototype.readFeature
-@exportProperty ol.format.IGC.prototype.readFeatures
-@exportProperty ol.format.IGC.prototype.readProjection

src/ol/format/igcformat.js

@@ -25,7 +25,7 @@ ol.format.IGCZ = {
  * @constructor
  * @extends {ol.format.TextFeature}
  * @param {olx.format.IGCOptions=} opt_options Options.
- * @todo stability experimental
+ * @todo api
  */
 ol.format.IGC = function(opt_options) {
 
@@ -91,6 +91,7 @@ ol.format.IGC.prototype.getExtensions = function() {
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {ol.Feature} Feature.
+ * @todo api
  */
 ol.format.IGC.prototype.readFeature;
 
@@ -176,6 +177,7 @@ ol.format.IGC.prototype.readFeatureFromText = function(text) {
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {Array.<ol.Feature>} Features.
+ * @todo api
  */
 ol.format.IGC.prototype.readFeatures;
 
@@ -199,6 +201,7 @@ ol.format.IGC.prototype.readFeaturesFromText = function(text) {
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {ol.proj.Projection} Projection.
+ * @todo api
  */
 ol.format.IGC.prototype.readProjection;
 

src/ol/format/kmlformat.exports

@@ -1,5 +0,0 @@
-@exportSymbol ol.format.KML
-@exportProperty ol.format.KML.prototype.readFeature
-@exportProperty ol.format.KML.prototype.readFeatures
-@exportProperty ol.format.KML.prototype.readName
-@exportProperty ol.format.KML.prototype.readProjection

src/ol/format/kmlformat.js

@@ -54,7 +54,7 @@ ol.format.KMLGxTrackObject_;
  * @constructor
  * @extends {ol.format.XMLFeature}
  * @param {olx.format.KMLOptions=} opt_options Options.
- * @todo stability experimental
+ * @todo api
  */
 ol.format.KML = function(opt_options) {
 
@@ -1450,6 +1450,7 @@ ol.format.KML.prototype.readSharedStyleMap_ = function(node, objectStack) {
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {ol.Feature} Feature.
+ * @todo api
  */
 ol.format.KML.prototype.readFeature;
 
@@ -1478,6 +1479,7 @@ ol.format.KML.prototype.readFeatureFromNode = function(node) {
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {Array.<ol.Feature>} Features.
+ * @todo api
  */
 ol.format.KML.prototype.readFeatures;
 
@@ -1526,7 +1528,6 @@ ol.format.KML.prototype.readFeaturesFromNode = function(node) {
 /**
  * @param {Document|Node|string} source Souce.
  * @return {string|undefined} Name.
- * @todo stability experimental
  */
 ol.format.KML.prototype.readName = function(source) {
   if (ol.xml.isDocument(source)) {
@@ -1596,6 +1597,7 @@ ol.format.KML.prototype.readNameFromNode = function(node) {
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {ol.proj.Projection} Projection.
+ * @todo api
  */
 ol.format.KML.prototype.readProjection;
 

src/ol/format/osmxmlformat.exports

@@ -1 +0,0 @@
-@exportSymbol ol.format.OSMXML

src/ol/format/osmxmlformat.js

@@ -18,6 +18,7 @@ goog.require('ol.xml');
 /**
  * @constructor
  * @extends {ol.format.XMLFeature}
+ * @todo api
  */
 ol.format.OSMXML = function() {
   goog.base(this);

src/ol/format/topojsonformat.exports

@@ -1,3 +0,0 @@
-@exportSymbol ol.format.TopoJSON
-@exportProperty ol.format.TopoJSON.prototype.readFeatures
-@exportProperty ol.format.TopoJSON.prototype.readProjection

src/ol/format/topojsonformat.js

@@ -19,7 +19,7 @@ goog.require('ol.proj');
  * @constructor
  * @extends {ol.format.JSONFeature}
  * @param {olx.format.TopoJSONOptions=} opt_options Options.
- * @todo stability experimental
+ * @todo api
  */
 ol.format.TopoJSON = function(opt_options) {
 
@@ -271,6 +271,7 @@ ol.format.TopoJSON.readFeatureFromGeometry_ = function(object, arcs,
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {Array.<ol.Feature>} Features.
+ * @todo api
  */
 ol.format.TopoJSON.prototype.readFeatures;
 
@@ -380,6 +381,7 @@ ol.format.TopoJSON.transformVertex_ = function(vertex, scale, translate) {
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} object Source.
  * @return {ol.proj.Projection} Projection.
+ * @todo api
  */
 ol.format.TopoJSON.prototype.readProjection = function(object) {
   return this.defaultProjection_;

src/ol/format/wfsformat.exports

@@ -1,6 +0,0 @@
-@exportSymbol ol.format.WFS
-@exportProperty ol.format.WFS.prototype.readFeatures
-@exportProperty ol.format.WFS.prototype.readTransactionResponse
-@exportProperty ol.format.WFS.prototype.readFeatureCollectionMetadata
-@exportProperty ol.format.WFS.prototype.writeGetFeature
-@exportProperty ol.format.WFS.prototype.writeTransaction

src/ol/format/wfsformat.js

@@ -17,7 +17,7 @@ goog.require('ol.xml');
  * @param {olx.format.WFSOptions=} opt_options
  *     Optional configuration object.
  * @extends {ol.format.XMLFeature}
- * @todo stability experimental
+ * @todo api
  */
 ol.format.WFS = function(opt_options) {
   var options = /** @type {olx.format.WFSOptions} */
@@ -92,6 +92,7 @@ ol.format.WFS.prototype.readFeaturesFromNode = function(node) {
 /**
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {ol.format.WFS.TransactionResponse|undefined} Transaction response.
+ * @todo api
  */
 ol.format.WFS.prototype.readTransactionResponse = function(source) {
   if (ol.xml.isDocument(source)) {
@@ -113,6 +114,7 @@ ol.format.WFS.prototype.readTransactionResponse = function(source) {
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {ol.format.WFS.FeatureCollectionMetadata|undefined}
  *     FeatureCollection metadata.
+ * @todo api
  */
 ol.format.WFS.prototype.readFeatureCollectionMetadata = function(source) {
   if (ol.xml.isDocument(source)) {
@@ -549,6 +551,7 @@ ol.format.WFS.writeGetFeature_ = function(node, featureTypes, objectStack) {
 /**
  * @param {olx.format.WFSWriteGetFeatureOptions} options Options.
  * @return {Node} Result.
+ * @todo api
  */
 ol.format.WFS.prototype.writeGetFeature = function(options) {
   var node = ol.xml.createElementNS('http://www.opengis.net/wfs',
@@ -600,6 +603,7 @@ ol.format.WFS.prototype.writeGetFeature = function(options) {
  * @param {Array.<ol.Feature>} deletes The features to delete.
  * @param {olx.format.WFSWriteTransactionOptions} options Write options.
  * @return {Node} Result.
+ * @todo api
  */
 ol.format.WFS.prototype.writeTransaction = function(inserts, updates, deletes,
     options) {

src/ol/format/wmscapabilitiesformat.exports

@@ -1,2 +0,0 @@
-@exportSymbol ol.format.WMSCapabilities
-@exportProperty ol.format.WMSCapabilities.prototype.read

src/ol/format/wmscapabilitiesformat.js

@@ -15,6 +15,7 @@ goog.require('ol.xml');
 /**
  * @constructor
  * @extends {ol.format.XML}
+ * @todo api
  */
 ol.format.WMSCapabilities = function() {
 
@@ -28,6 +29,17 @@ ol.format.WMSCapabilities = function() {
 goog.inherits(ol.format.WMSCapabilities, ol.format.XML);
 
 
+/**
+ * Read a WMS capabilities document.
+ *
+ * @function
+ * @param {Document|Node|string} source The XML source.
+ * @return {Object} An object representing the WMS capabilities.
+ * @todo api
+ */
+ol.format.WMSCapabilities.prototype.read;
+
+
 /**
  * @param {Document} doc Document.
  * @return {Object} WMS Capability object.

src/ol/framestate.js

@@ -12,6 +12,11 @@ ol.PostRenderFunction;
 
 
 /**
+ * Function to perform manipulations before rendering. This function is called
+ * with the {@link ol.Map} as first and an optional {@link oli.FrameState} as
+ * second argument. Return `true` to keep this function for the next frame,
+ * `false` to remove it.
  * @typedef {function(ol.Map, ?oli.FrameState): boolean}
+ * @todo api
  */
 ol.PreRenderFunction;

src/ol/geolocation.exports

@@ -1 +0,0 @@
-@exportSymbol ol.Geolocation

src/ol/geolocation.js

@@ -51,7 +51,6 @@ ol.GeolocationProperty = {
  * @constructor
  * @extends {ol.Object}
  * @param {olx.GeolocationOptions=} opt_options Options.
- * @todo stability experimental
  * @todo observable accuracy {number} readonly the accuracy of the position
  *       measurement in meters
  * @todo observable accuracyGeometry {ol.geom.Geometry} readonly a
@@ -72,6 +71,7 @@ ol.GeolocationProperty = {
  * @todo observable trackingOptions {GeolocationPositionOptions} PositionOptions
  *       as defined by the HTML5 Geolocation spec at
  *       http://www.w3.org/TR/geolocation-API/#position_options_interface
+ * @todo api
  */
 ol.Geolocation = function(opt_options) {
 
@@ -206,7 +206,7 @@ ol.Geolocation.prototype.positionError_ = function(error) {
 /**
  * Get the accuracy of the position in meters.
  * @return {number|undefined} Position accuracy in meters.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.getAccuracy = function() {
   return /** @type {number|undefined} */ (
@@ -221,7 +221,7 @@ goog.exportProperty(
 /**
  * Get a geometry of the position accuracy.
  * @return {?ol.geom.Geometry} Accuracy geometry.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.getAccuracyGeometry = function() {
   return /** @type {?ol.geom.Geometry} */ (
@@ -236,7 +236,7 @@ goog.exportProperty(
 /**
  * Get the altitude associated with the position.
  * @return {number|undefined} The altitude in meters above the mean sea level.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.getAltitude = function() {
   return /** @type {number|undefined} */ (
@@ -251,7 +251,7 @@ goog.exportProperty(
 /**
  * Get the altitude accuracy of the position.
  * @return {number|undefined} Altitude accuracy in meters.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.getAltitudeAccuracy = function() {
   return /** @type {number|undefined} */ (
@@ -266,7 +266,7 @@ goog.exportProperty(
 /**
  * Get the heading as radians clockwise from North.
  * @return {number|undefined} Heading.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.getHeading = function() {
   return /** @type {number|undefined} */ (
@@ -281,7 +281,7 @@ goog.exportProperty(
 /**
  * Get the position of the device.
  * @return {ol.Coordinate|undefined} position.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.getPosition = function() {
   return /** @type {ol.Coordinate|undefined} */ (
@@ -296,7 +296,7 @@ goog.exportProperty(
 /**
  * Get the projection associated with the position.
  * @return {ol.proj.Projection|undefined} projection.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.getProjection = function() {
   return /** @type {ol.proj.Projection|undefined} */ (
@@ -311,7 +311,7 @@ goog.exportProperty(
 /**
  * Get the speed in meters per second.
  * @return {number|undefined} Speed.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.getSpeed = function() {
   return /** @type {number|undefined} */ (
@@ -326,7 +326,7 @@ goog.exportProperty(
 /**
  * Are we tracking the user's position?
  * @return {boolean} tracking.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.getTracking = function() {
   return /** @type {boolean} */ (
@@ -343,7 +343,7 @@ goog.exportProperty(
  * @see http://www.w3.org/TR/geolocation-API/#position-options
  * @return {GeolocationPositionOptions|undefined} HTML 5 Gelocation
  * tracking options.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.getTrackingOptions = function() {
   return /** @type {GeolocationPositionOptions|undefined} */ (
@@ -358,7 +358,7 @@ goog.exportProperty(
 /**
  * Set the projection to use for transforming the coordinates.
  * @param {ol.proj.Projection} projection Projection.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.setProjection = function(projection) {
   this.set(ol.GeolocationProperty.PROJECTION, projection);
@@ -372,7 +372,7 @@ goog.exportProperty(
 /**
  * Enable/disable tracking.
  * @param {boolean} tracking Enable or disable tracking.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.setTracking = function(tracking) {
   this.set(ol.GeolocationProperty.TRACKING, tracking);
@@ -388,7 +388,7 @@ goog.exportProperty(
  * @see http://www.w3.org/TR/geolocation-API/#position-options
  * @param {GeolocationPositionOptions} options HTML 5 Geolocation
  * tracking options.
- * @todo stability experimental
+ * @todo api
  */
 ol.Geolocation.prototype.setTrackingOptions = function(options) {
   this.set(ol.GeolocationProperty.TRACKING_OPTIONS, options);

src/ol/geom/circle.exports

@@ -1,11 +0,0 @@
-@exportSymbol ol.geom.Circle
-@exportProperty ol.geom.Circle.prototype.clone
-@exportProperty ol.geom.Circle.prototype.getCenter
-@exportProperty ol.geom.Circle.prototype.getExtent
-@exportProperty ol.geom.Circle.prototype.getRadius
-@exportProperty ol.geom.Circle.prototype.getSimplifiedGeometry
-@exportProperty ol.geom.Circle.prototype.getType
-@exportProperty ol.geom.Circle.prototype.setCenter
-@exportProperty ol.geom.Circle.prototype.setCenterAndRadius
-@exportProperty ol.geom.Circle.prototype.setRadius
-@exportProperty ol.geom.Circle.prototype.transform

src/ol/geom/circle.js

@@ -14,7 +14,7 @@ goog.require('ol.geom.flat.deflate');
  * @param {ol.geom.RawPoint} center Center.
  * @param {number=} opt_radius Radius.
  * @param {ol.geom.GeometryLayout|string=} opt_layout Layout.
- * @todo stability experimental
+ * @todo api
  */
 ol.geom.Circle = function(center, opt_radius, opt_layout) {
   goog.base(this);
@@ -27,6 +27,7 @@ goog.inherits(ol.geom.Circle, ol.geom.SimpleGeometry);
 
 /**
  * @inheritDoc
+ * @todo api
  */
 ol.geom.Circle.prototype.clone = function() {
   var circle = new ol.geom.Circle(null);
@@ -79,7 +80,7 @@ ol.geom.Circle.prototype.containsXY = function(x, y) {
 
 /**
  * @return {ol.geom.RawPoint} Center.
- * @todo stability experimental
+ * @todo api
  */
 ol.geom.Circle.prototype.getCenter = function() {
   return this.flatCoordinates.slice(0, this.stride);
@@ -88,6 +89,7 @@ ol.geom.Circle.prototype.getCenter = function() {
 
 /**
  * @inheritDoc
+ * @todo api
  */
 ol.geom.Circle.prototype.getExtent = function(opt_extent) {
   if (this.extentRevision != this.getRevision()) {
@@ -106,7 +108,7 @@ ol.geom.Circle.prototype.getExtent = function(opt_extent) {
 
 /**
  * @return {number} Radius.
- * @todo stability experimental
+ * @todo api
  */
 ol.geom.Circle.prototype.getRadius = function() {
   return Math.sqrt(this.getRadiusSquared_());
@@ -126,6 +128,7 @@ ol.geom.Circle.prototype.getRadiusSquared_ = function() {
 
 /**
  * @inheritDoc
+ * @todo api
  */
 ol.geom.Circle.prototype.getSimplifiedGeometry = function(squaredTolerance) {
   return this;
@@ -134,6 +137,7 @@ ol.geom.Circle.prototype.getSimplifiedGeometry = function(squaredTolerance) {
 
 /**
  * @inheritDoc
+ * @todo api
  */
 ol.geom.Circle.prototype.getType = function() {
   return ol.geom.GeometryType.CIRCLE;
@@ -142,7 +146,7 @@ ol.geom.Circle.prototype.getType = function() {
 
 /**
  * @param {ol.geom.RawPoint} center Center.
- * @todo stability experimental
+ * @todo api
  */
 ol.geom.Circle.prototype.setCenter = function(center) {
   var stride = this.stride;
@@ -162,7 +166,7 @@ ol.geom.Circle.prototype.setCenter = function(center) {
  * @param {ol.geom.RawPoint} center Center.
  * @param {number} radius Radius.
  * @param {ol.geom.GeometryLayout=} opt_layout Layout.
- * @todo stability experimental
+ * @todo api
  */
 ol.geom.Circle.prototype.setCenterAndRadius =
     function(center, radius, opt_layout) {
@@ -201,7 +205,7 @@ ol.geom.Circle.prototype.setFlatCoordinates =
 
 /**
  * @param {number} radius Radius.
- * @todo stability experimental
+ * @todo api
  */
 ol.geom.Circle.prototype.setRadius = function(radius) {
   goog.asserts.assert(!goog.isNull(this.flatCoordinates));

src/ol/geom/geometry.exports

@@ -1,3 +0,0 @@
-@exportSymbol ol.geom.Geometry
-@exportProperty ol.geom.Geometry.prototype.getClosestPoint
-@exportProperty ol.geom.Geometry.prototype.getType