Merge pull request #1979 from tschaub/custom-build

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

Fixes #613.

.travis.yml

@@ -1,10 +1,5 @@
 before_install:
   - "sudo pip install -r requirements.txt"
-  - "git clone --depth=50 https://github.com/jsdoc3/jsdoc build/jsdoc"
-  - "cd build/jsdoc"
-  - "git fetch origin refs/tags/v3.2.2:refs/tags/v3.2.2"
-  - "git checkout tags/v3.2.2"
-  - "cd ../.."
   - "npm install"
 
 before_script:
@@ -13,4 +8,4 @@ before_script:
   - "rm src/ol/renderer/webgl/*shader.js"
   - "sleep 3"
 
-script: "./build.py JSDOC=build/jsdoc/jsdoc integration-test"
+script: "./build.py integration-test"

apidoc/conf.json

@@ -13,16 +13,20 @@
             "src/googx/dom/fullscreen.js"
         ],
         "include": [
-            "src"
+            "src",
+            "externs/oli.js",
+            "externs/olx.js"
         ]
     },
     "plugins": [
-        "plugins/markdown",
+        "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,118 +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 == "objectliterals.jsdoc" && e.doclet.properties) {
-      for (i = 0, ii = e.doclet.properties.length; i < ii; ++i) {
-        if (e.doclet.properties[i].type && e.doclet.properties[i].type.names) {
-          for (j = 0, jj = e.doclet.properties[i].type.names.length; j < jj; ++j) {
-            if (e.doclet.properties[i].type.names[j].indexOf('ol') == 0) {
-              if (api.indexOf(e.doclet.properties[i].type.names[j]) === -1) {
-                api.push(e.doclet.properties[i].type.names[j]);
-              }
-            }
-          }
-        }
-      }
-    }
-    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.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.nodeVisitor = {
 
-  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/publish.js

@@ -1,7 +1,7 @@
 /*global env: true */
 var template = require('jsdoc/template'),
-    fs = require('fs'),
-    path = require('path'),
+    fs = require('jsdoc/fs'),
+    path = require('jsdoc/path'),
     taffy = require('taffydb').taffy,
     helper = require('jsdoc/util/templateHelper'),
     scopeToPunc = helper.scopeToPunc,

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,219 +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 ''
-
-    def extern(self):
-        return ''
-
-    def typedef(self):
-        return ''
-
-
-class ObjectLiteral(Exportable):
-
-    def __init__(self, name, objects):
-        Exportable.__init__(self, name)
-        self.prop_types = {}
-        self.objects = objects
-
-    __repr__ = simplerepr
-
-    def extern(self):
-        lines = []
-        lines.append('\n\n\n')
-        lines.append('/**\n')
-        lines.append(' * @interface\n')
-        lines.append(' */\n')
-        lines.append('%s = function() {};\n' % (self.extern_name(),))
-        for prop in sorted(self.prop_types.keys()):
-            lines.append('\n\n')
-            lines.append('/**\n')
-            prop_types = self.prop_types[prop].split('|')
-            for i, t in enumerate(prop_types):
-                if t in self.objects and isinstance(self.objects[t], ObjectLiteral):
-                    prop_types[i] = self.objects[t].extern_name()
-            prop_types = '|'.join(prop_types)
-            lines.append(' * @type {%s}\n' % (prop_types,))
-            lines.append(' */\n')
-            lines.append('%s.prototype.%s;\n' % (self.extern_name(), prop))
-        return ''.join(lines)
-
-    def extern_name(self):
-        return re.sub(r'(olx\.\S+)', r'\1Extern', self.name)
-
-    def extern_namespace(self):
-        return '.'.join(self.extern_name().split('.')[:-1]) or None
-
-    def provide(self):
-        return 'goog.provide(\'%s\');\n' % (self.name,)
-
-    def typedef(self):
-        lines = []
-        lines.append('\n\n')
-        lines.append('/**\n')
-        for i, prop in enumerate(sorted(self.prop_types.keys())):
-            prefix =  ' * @typedef {{' if i == 0 else ' *            '
-            suffix = '}}' if i == len(self.prop_types) - 1 else ','
-            type = self.prop_types[prop]
-            if '|' in type:
-                type = '(%s)' % (type,)
-            lines.append('%s%s: %s%s\n' % (prefix, prop, type, suffix))
-        lines.append(' */\n')
-        lines.append('%s;\n' % (self.name,))
-        return ''.join(lines)
-
-
-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')
-    option_parser.add_option('--externs', action='store_true')
-    option_parser.add_option('--typedef', action='store_true')
-    options, args = option_parser.parse_args(argv[1:])
-
-    objects = {}
-    requires = set()
-    for arg in args:
-        in_comment = False
-        object_literal = None
-        for line in open(arg, 'rU'):
-            line = line.strip()
-            if not line:
-                continue
-            if line == '/**':
-                assert not in_comment
-                in_comment = True
-                continue
-            if line == '*/':
-                assert in_comment
-                in_comment = False
-                object_literal = None
-                continue
-            if in_comment:
-                if not line.startswith('*'):
-                    raise RuntimeError(line)  # malformed comment
-                m = re.match(r'\*\s*@typedef\s*\{Object\}\s*(?P<name>\S+)', line)
-                if m:
-                    assert object_literal is None
-                    name = m.group('name')
-                    if name in objects:
-                        raise RuntimeError(line)  # Name already defined
-                    object_literal = ObjectLiteral(name, objects)
-                    objects[name] = object_literal
-                    continue
-                m = re.match(r'\*\s*@property\s*{(?P<type>.*?)}\s*(?P<prop>\S+)', line)
-                if m:
-                    assert object_literal is not None
-                    prop = m.group('prop')
-                    if prop in object_literal.prop_types:
-                        raise RuntimeError(line)  # Duplicate property
-                    type = m.group('type')
-                    object_literal.prop_types[prop] = type
-                    continue
-                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 options.externs:
-        object_literals = [obj for obj in objects if isinstance(obj, ObjectLiteral)]
-        sys.stdout.write('/**\n')
-        sys.stdout.write(' * @externs\n')
-        sys.stdout.write(' */\n')
-        namespaces = sorted(set(filter(None, (object_literal.extern_namespace() for object_literal in object_literals))))
-        for namespace in namespaces:
-            sys.stdout.write('\n\n')
-            sys.stdout.write('/**\n')
-            sys.stdout.write(' * @type {Object}\n')
-            sys.stdout.write(' */\n')
-            if '.' in namespace:
-                sys.stdout.write('%s = {};\n' % (namespace,))
-            else:
-                sys.stdout.write('var %s;\n' % (namespace,))
-        for object_literal in object_literals:
-            sys.stdout.write(object_literal.typedef())
-            sys.stdout.write(object_literal.extern())
-
-    if options.typedef:
-        object_literals = [obj for obj in objects if isinstance(obj, ObjectLiteral)]
-        for object_literal in object_literals:
-            sys.stdout.write(object_literal.provide())
-        for object_literal in object_literals:
-            sys.stdout.write(object_literal.typedef())
-
-
-if __name__ == '__main__':
-    sys.exit(main(sys.argv))

build.py

@@ -20,7 +20,7 @@ if sys.platform == 'win32':
         'GJSLINT': 'gjslint.exe',
         'JAVA': 'java.exe',
         'JAR': 'jar.exe',
-        'JSDOC': 'jsdoc.cmd',
+        'JSDOC': './node_modules/.bin/jsdoc',
         'JSHINT': './node_modules/.bin/jshint',
         'PYTHON': 'python.exe',
         'PHANTOMJS': 'phantomjs.cmd'
@@ -75,7 +75,7 @@ else:
     variables.JSHINT = './node_modules/.bin/jshint'
     variables.JAVA = 'java'
     variables.JAR = 'jar'
-    variables.JSDOC = 'jsdoc'
+    variables.JSDOC = './node_modules/.bin/jsdoc'
     variables.PYTHON = 'python'
     variables.PHANTOMJS = 'phantomjs'
 
@@ -86,13 +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/externs/types.js',
-    'build/src/external/src/exports.js']
+EXPORTS = 'build/exports.js'
 
 EXAMPLES = [path
             for path in ifind('examples')
@@ -115,10 +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',
-    'build/src/internal/src/types.js']
-
 GLSL_SRC = [path
             for path in ifind('src')
             if path.endswith('.glsl')]
@@ -186,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):
@@ -203,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',
@@ -215,26 +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/externs/types.js', 'bin/generate-exports.py',
-        'src/objectliterals.jsdoc')
-def build_src_external_externs_types_js(t):
-    t.output('%(PYTHON)s', 'bin/generate-exports.py',
-             '--externs', 'src/objectliterals.jsdoc')
-
-
-@target('build/src/external/src/exports.js', 'bin/generate-exports.py',
-        'src/objectliterals.jsdoc', EXPORTS)
-def build_src_external_src_exports_js(t):
-    t.output('%(PYTHON)s', 'bin/generate-exports.py',
-             '--exports', 'src/objectliterals.jsdoc', EXPORTS)
+@target(EXPORTS, SRC)
+def build_exports_js(t):
+    t.run('node', 'tasks/generate-exports.js', EXPORTS)
 
 
 for glsl_src in GLSL_SRC:
@@ -249,36 +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)
-
-
-@target('build/src/internal/src/types.js', 'bin/generate-exports.py',
-        'src/objectliterals.jsdoc')
-def build_src_internal_types_js(t):
-    t.output('%(PYTHON)s', 'bin/generate-exports.py',
-             '--typedef', 'src/objectliterals.jsdoc')
-
-
 virtual('build-examples', 'examples', 'build/examples/all.combined.js',
         EXAMPLES_COMBINED)
 
@@ -297,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',
@@ -313,12 +276,16 @@ def build_examples_all_js(t):
 @rule(r'\Abuild/examples/(?P<id>.*).json\Z')
 def examples_star_json(name, match):
     def action(t):
+        # It would make more sense to use olx.js as an input file here. We use
+        # it as an externs file instead to prevent "Cannot read property '*' of
+        # undefined" error when running examples in "raw" or "whitespace" mode.
+        # Note that we use the proper way in buildcfg/examples-all.json, which
+        # is only used to check the examples code using the compiler.
         content = json.dumps({
             'id': match.group('id'),
             'inherits': '../../buildcfg/base.json',
             'inputs': [
-                '../examples/%(id)s.js' % match.groupdict(),
-                '../build/src/internal/src/types.js',
+                '../examples/%(id)s.js' % match.groupdict()
             ],
             'externs': [
                 '//jquery-1.7.js',
@@ -328,6 +295,7 @@ def examples_star_json(name, match):
                 '../externs/example.js',
                 '../externs/geojson.js',
                 '../externs/oli.js',
+                '../externs/olx.js',
                 '../externs/proj4js.js',
                 '../externs/tilejson.js',
                 '../externs/topojson.js',
@@ -347,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()]
@@ -360,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',
@@ -381,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', 'build/src/external/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',
@@ -413,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()
@@ -443,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
@@ -463,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()
@@ -544,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()
@@ -588,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+')
@@ -637,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',
@@ -750,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

@@ -51,6 +51,7 @@
     "../externs/closure-compiler.js",
     "../externs/geojson.js",
     "../externs/oli.js",
+    "../externs/olx.js",
     "../externs/proj4js.js",
     "../externs/tilejson.js",
     "../externs/topojson.js",
@@ -67,7 +68,6 @@
   ],
 
   "paths": [
-    "../build/src/internal/src",
     "../src"
   ],
 

buildcfg/examples-all.json

@@ -16,6 +16,6 @@
     "inherits": "base.json", 
     "inputs": [
         "../build/examples/all.js", 
-        "../build/src/internal/src/types.js"
+        "../externs/olx.js"
     ]
 }

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

@@ -3,11 +3,11 @@
   "id": "ol-all",
 
   "externs": [
-    "../build/src/external/externs/types.js",
     "../externs/bingmaps.js",
     "../externs/closure-compiler.js",
     "../externs/geojson.js",
     "../externs/oli.js",
+    "../externs/olx.js",
     "../externs/proj4js.js",
     "../externs/tilejson.js",
     "../externs/topojson.js",
@@ -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

@@ -13,11 +13,11 @@
   "id": "ol-simple",
 
   "externs": [
-    "../build/src/external/externs/types.js",
     "../externs/bingmaps.js",
     "../externs/closure-compiler.js",
     "../externs/geojson.js",
     "../externs/oli.js",
+    "../externs/olx.js",
     "../externs/proj4js.js",
     "../externs/tilejson.js",
     "../externs/topojson.js",
@@ -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

@@ -18,6 +18,7 @@
     "../externs/closure-compiler.js",
     "../externs/geojson.js",
     "../externs/oli.js",
+    "../externs/olx.js",
     "../externs/proj4js.js",
     "../externs/tilejson.js",
     "../externs/topojson.js",
@@ -27,7 +28,7 @@
   "inherits": "ol.json",
 
   "inputs": [
-    "../build/src/internal/src/requireall.js"
+    "../build/exports.js"
   ],
 
   "mode": "WHITESPACE",

buildcfg/ol.json

@@ -13,11 +13,11 @@
   "css-output-file": "../build/ol.css",
 
   "externs": [
-    "../build/src/external/externs/types.js",
     "../externs/bingmaps.js",
     "../externs/closure-compiler.js",
     "../externs/geojson.js",
     "../externs/oli.js",
+    "../externs/olx.js",
     "../externs/proj4js.js",
     "../externs/tilejson.js",
     "../externs/topojson.js",
@@ -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%})();",

examples/animation.html

@@ -32,6 +32,7 @@
         <div class="span12">
           <button id="rotate-left"><i class="icon-arrow-left"></i></button>
           <button id="rotate-right"><i class="icon-arrow-right"></i></button>
+          <button id="rotate-around-rome">Rotate around Rome</button>
           <button id="pan-to-london">Pan to London</button>
           <button id="elastic-to-moscow">Elastic to Moscow</button>
           <button id="bounce-to-istanbul">Bounce to Istanbul</button>

examples/animation.js

@@ -49,6 +49,17 @@ rotateRight.addEventListener('click', function() {
   map.beforeRender(rotateRight);
 }, false);
 
+var rotateAroundRome = document.getElementById('rotate-around-rome');
+rotateAroundRome.addEventListener('click', function() {
+  var currentRotation = view.getRotation();
+  var rotateAroundRome = ol.animation.rotate({
+    anchor: rome,
+    duration: 1000,
+    rotation: currentRotation
+  });
+  map.beforeRender(rotateAroundRome);
+  view.rotate(currentRotation + (Math.PI / 2), rome);
+}, false);
 
 var panToLondon = document.getElementById('pan-to-london');
 panToLondon.addEventListener('click', function() {

examples/measure.html

@@ -0,0 +1,65 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="chrome=1">
+    <meta name="viewport" content="initial-scale=1.0, user-scalable=no, width=device-width">
+    <link rel="stylesheet" href="../css/ol.css" type="text/css">
+    <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap.min.css" type="text/css">
+    <link rel="stylesheet" href="../resources/layout.css" type="text/css">
+    <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap-responsive.min.css" type="text/css">
+    <title>Measure example</title>
+  </head>
+  <body>
+
+    <div class="navbar navbar-inverse navbar-fixed-top">
+      <div class="navbar-inner">
+        <div class="container">
+          <a class="brand" href="./"><img src="../resources/logo.png"> OpenLayers 3 Examples</a>
+        </div>
+      </div>
+    </div>
+
+    <div class="container-fluid">
+
+      <div class="row-fluid">
+        <div class="span12">
+          <div id="map" class="map"></div>
+        </div>
+      </div>
+
+      <div class="row-fluid">
+
+        <div class="span12">
+          <h4 id="title">Measure example</h4>
+          <p id="shortdesc">Example of using the
+          ol.interaction.Draw interaction for creating simple
+          measuring application. </p>
+          <form class="form-inline">
+            <label>Geometry type &nbsp;</label>
+              <select id="type">
+                <option value="length">Length</option>
+                <option value="area">Area</option>
+              </select>
+          </form>
+
+          <ol id="measureOutput" reversed></ol>
+
+          <div id="docs">
+              <p><i>NOTE: Measure is done in simple way on projected plane. Earth
+              curvature is not taken into account</i></p>
+            <p>See the <a href="measure.js" target="_blank">measure.js source</a> to see how this is done.</p>
+          </div>
+          <div id="tags">draw, edit, measure, vector</div>
+        </div>
+
+      </div>
+
+    </div>
+
+    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/example-behaviour.js" type="text/javascript"></script>
+    <script src="loader.js?id=measure" type="text/javascript"></script>
+
+  </body>
+</html>

examples/measure.js

@@ -0,0 +1,167 @@
+goog.require('ol.Map');
+goog.require('ol.View2D');
+goog.require('ol.geom.LineString');
+goog.require('ol.geom.Polygon');
+goog.require('ol.interaction');
+goog.require('ol.interaction.Draw');
+goog.require('ol.layer.Tile');
+goog.require('ol.layer.Vector');
+goog.require('ol.source.MapQuest');
+goog.require('ol.source.Vector');
+goog.require('ol.style.Circle');
+goog.require('ol.style.Fill');
+goog.require('ol.style.Stroke');
+goog.require('ol.style.Style');
+
+var raster = new ol.layer.Tile({
+  source: new ol.source.MapQuest({layer: 'sat'})
+});
+
+var source = new ol.source.Vector();
+
+var vector = new ol.layer.Vector({
+  source: source,
+  style: new ol.style.Style({
+    fill: new ol.style.Fill({
+      color: 'rgba(255, 255, 255, 0.2)'
+    }),
+    stroke: new ol.style.Stroke({
+      color: '#ffcc33',
+      width: 2
+    }),
+    image: new ol.style.Circle({
+      radius: 7,
+      fill: new ol.style.Fill({
+        color: '#ffcc33'
+      })
+    })
+  })
+});
+
+
+/**
+ * Currently drawed feature
+ * @type {ol.Feature}
+ */
+var sketch;
+
+
+/**
+ * Element for currently drawed feature
+ * @type {Element}
+ */
+var sketchElement;
+
+
+/**
+ * handle pointer move
+ * @param {Event} evt
+ */
+var mouseMoveHandler = function(evt) {
+  if (sketch) {
+    var output;
+    var geom = (sketch.getGeometry());
+    if (geom instanceof ol.geom.Polygon) {
+      output = formatArea(/** @type {ol.geom.Polygon} */ (geom));
+
+    } else if (geom instanceof ol.geom.LineString) {
+      output = formatLength( /** @type {ol.geom.LineString} */ (geom));
+    }
+    sketchElement.innerHTML = output;
+  }
+};
+
+
+var map = new ol.Map({
+  layers: [raster, vector],
+  target: 'map',
+  view: new ol.View2D({
+    center: [-11000000, 4600000],
+    zoom: 15
+  })
+});
+
+$(map.getViewport()).on('mousemove', mouseMoveHandler);
+
+var typeSelect = document.getElementById('type');
+
+var draw; // global so we can remove it later
+function addInteraction() {
+  var type = (typeSelect.value == 'area' ? 'Polygon' : 'LineString');
+  draw = new ol.interaction.Draw({
+    source: source,
+    type: /** @type {ol.geom.GeometryType} */ (type)
+  });
+  map.addInteraction(draw);
+
+  draw.on('drawstart',
+      function(evt) {
+        // set sketch
+        sketch = evt.feature;
+        sketchElement = document.createElement('li');
+        var outputList = document.getElementById('measureOutput');
+
+        if (outputList.childNodes) {
+          outputList.insertBefore(sketchElement, outputList.firstChild);
+        } else {
+          outputList.appendChild(sketchElement);
+        }
+      }, this);
+
+  draw.on('drawend',
+      function(evt) {
+        // unset sketch
+        sketch = null;
+        sketchElement = null;
+      }, this);
+}
+
+
+/**
+ * Let user change the geometry type.
+ * @param {Event} e Change event.
+ */
+typeSelect.onchange = function(e) {
+  map.removeInteraction(draw);
+  addInteraction();
+};
+
+
+/**
+ * format length output
+ * @param {ol.geom.LineString} line
+ * @return {string}
+ */
+var formatLength = function(line) {
+  var length = Math.round(line.getLength() * 100) / 100;
+  var output;
+  if (length > 100) {
+    output = (Math.round(length / 1000 * 100) / 100) +
+        ' ' + 'km';
+  } else {
+    output = (Math.round(length * 100) / 100) +
+        ' ' + 'm';
+  }
+  return output;
+};
+
+
+/**
+ * format length output
+ * @param {ol.geom.Polygon} polygon
+ * @return {string}
+ */
+var formatArea = function(polygon) {
+  var area = polygon.getArea();
+  var output;
+  if (area > 10000) {
+    output = (Math.round(area / 1000000 * 100) / 100) +
+        ' ' + 'km<sup>2</sup>';
+  } else {
+    output = (Math.round(area * 100) / 100) +
+        ' ' + 'm<sup>2</sup>';
+  }
+  return output;
+};
+
+addInteraction();

examples/tissot.html

@@ -0,0 +1,51 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="chrome=1">
+    <meta name="viewport" content="initial-scale=1.0, user-scalable=no, width=device-width">
+    <link rel="stylesheet" href="../css/ol.css" type="text/css">
+    <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap.min.css" type="text/css">
+    <link rel="stylesheet" href="../resources/layout.css" type="text/css">
+    <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap-responsive.min.css" type="text/css">
+    <title>Tissot indicatrix example</title>
+  </head>
+  <body>
+
+    <div class="navbar navbar-inverse navbar-fixed-top">
+      <div class="navbar-inner">
+        <div class="container">
+          <a class="brand" href="./"><img src="../resources/logo.png"> OpenLayers 3 Examples</a>
+        </div>
+      </div>
+    </div>
+
+    <div class="container-fluid">
+
+      <div class="row-fluid">
+        <div class="span12">
+          <div id="map" class="map"></div>
+        </div>
+      </div>
+
+      <div class="row-fluid">
+
+        <div class="span12">
+          <h4 id="title">Tissot indicatrix example</h4>
+          <p id="shortdesc">Example of a <a href="http://en.wikipedia.org/wiki/Tissot's_indicatrix">Tissot indicatrix</a> map.</p>
+          <div id="docs">
+            <p>See the <a href="tissot.js" target="_blank">tissot.js source</a> to see how this is done.</p>
+          </div>
+          <div id="tags">tissot, circle</div>
+        </div>
+
+      </div>
+
+    </div>
+
+    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/example-behaviour.js" type="text/javascript"></script>
+    <script src="loader.js?id=tissot" type="text/javascript"></script>
+
+  </body>
+</html>

examples/tissot.js

@@ -0,0 +1,44 @@
+goog.require('ol.Feature');
+goog.require('ol.Map');
+goog.require('ol.View2D');
+goog.require('ol.layer.Tile');
+goog.require('ol.layer.Vector');
+goog.require('ol.source.TileWMS');
+goog.require('ol.source.Vector');
+goog.require('ol.sphere.WGS84');
+
+var vectorSource = new ol.source.Vector();
+
+var map = new ol.Map({
+  layers: [
+    new ol.layer.Tile({
+      source: new ol.source.TileWMS({
+        url: 'http://vmap0.tiles.osgeo.org/wms/vmap0',
+        params: {
+          'VERSION': '1.1.1',
+          'LAYERS': 'basic',
+          'FORMAT': 'image/jpeg'
+        }
+      })
+    }),
+    new ol.layer.Vector({
+      source: vectorSource
+    })
+  ],
+  renderer: 'canvas',
+  target: 'map',
+  view: new ol.View2D({
+    projection: 'EPSG:4326',
+    center: [0, 0],
+    zoom: 2
+  })
+});
+
+
+var radius = 800000;
+for (var x = -180; x < 180; x += 30) {
+  for (var y = -90; y < 90; y += 30) {
+    var geometry = ol.sphere.WGS84.circle([x, y], radius, 64);
+    vectorSource.addFeature(new ol.Feature(geometry));
+  }
+}

examples/vector-wfs.html

@@ -0,0 +1,56 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="chrome=1">
+    <meta name="viewport" content="initial-scale=1.0, user-scalable=no, width=device-width">
+    <link rel="stylesheet" href="../css/ol.css" type="text/css">
+    <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap.min.css" type="text/css">
+    <link rel="stylesheet" href="../resources/layout.css" type="text/css">
+    <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap-responsive.min.css" type="text/css">
+    <title>WFS example</title>
+  </head>
+  <body>
+
+    <div class="navbar navbar-inverse navbar-fixed-top">
+      <div class="navbar-inner">
+        <div class="container">
+          <a class="brand" href="./"><img src="../resources/logo.png"> OpenLayers 3 Examples</a>          
+        </div>
+      </div>
+    </div>
+
+    <div class="container-fluid">
+
+      <div class="row-fluid">
+        <div class="span12">
+          <div id="map" class="map"></div>
+        </div>
+      </div>
+
+      <div class="row-fluid">
+
+        <div class="span4">
+          <h4 id="title">WFS example</h4>
+          <p id="shortdesc">Example of using WFS with a BBOX strategy.</p>
+          <div id="docs">
+            <p>See the <a href="vector-wfs.js" target="_blank">vector-wfs.js source</a> to see how this is done.</p>
+          </div>
+          <div id="tags">vector, WFS, bbox, loading, server</div>
+        </div>
+        <div class="span4 offset4">
+          <div id="info" class="alert alert-success">
+            &nbsp;
+          </div>
+        </div>
+
+      </div>
+
+    </div>
+
+    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/example-behaviour.js" type="text/javascript"></script>
+    <script src="loader.js?id=vector-wfs" type="text/javascript"></script>
+
+  </body>
+</html>

examples/vector-wfs.js

@@ -0,0 +1,60 @@
+goog.require('ol.Map');
+goog.require('ol.View2D');
+goog.require('ol.format.GeoJSON');
+goog.require('ol.layer.Tile');
+goog.require('ol.layer.Vector');
+goog.require('ol.loadingstrategy');
+goog.require('ol.source.BingMaps');
+goog.require('ol.source.ServerVector');
+goog.require('ol.style.Stroke');
+goog.require('ol.style.Style');
+goog.require('ol.tilegrid.XYZ');
+
+var loadFeatures = function(response) {
+  vectorSource.addFeatures(vectorSource.readFeatures(response));
+};
+
+var vectorSource = new ol.source.ServerVector({
+  format: new ol.format.GeoJSON(),
+  loader: function(extent, resolution, projection) {
+    var url = 'http://demo.opengeo.org/geoserver/wfs?service=WFS&' +
+        'version=1.1.0&request=GetFeature&typename=osm:water_areas&' +
+        'outputFormat=text/javascript&format_options=callback:loadFeatures' +
+        '&srsname=EPSG:3857&bbox=' + extent.join(',') + ',EPSG:3857';
+    $.ajax({
+      url: url,
+      dataType: 'jsonp'
+    });
+  },
+  strategy: ol.loadingstrategy.createTile(new ol.tilegrid.XYZ({
+    maxZoom: 19
+  })),
+  projection: 'EPSG:3857'
+});
+
+var vector = new ol.layer.Vector({
+  source: vectorSource,
+  style: new ol.style.Style({
+    stroke: new ol.style.Stroke({
+      color: 'rgba(0, 0, 255, 1.0)',
+      width: 2
+    })
+  })
+});
+
+var raster = new ol.layer.Tile({
+  source: new ol.source.BingMaps({
+    imagerySet: 'Aerial',
+    key: 'Ak-dzM4wZjSqTlzveKz5u0d4IQ4bRzVI309GxmkgSVr1ewS6iPSrOvOKhA-CJlm3'
+  })
+});
+
+var map = new ol.Map({
+  layers: [raster, vector],
+  target: document.getElementById('map'),
+  view: new ol.View2D({
+    center: [-8908887.277395891, 5381918.072437216],
+    maxZoom: 19,
+    zoom: 12
+  })
+});

examples/wmts.js

@@ -1,3 +1,4 @@
+goog.require('ol.Attribution');
 goog.require('ol.Map');
 goog.require('ol.View2D');
 goog.require('ol.extent');
@@ -8,17 +9,23 @@ goog.require('ol.source.WMTS');
 goog.require('ol.tilegrid.WMTS');
 
 
-var projection = ol.proj.get('EPSG:900913');
+var projection = ol.proj.get('EPSG:3857');
 var projectionExtent = projection.getExtent();
 var size = ol.extent.getWidth(projectionExtent) / 256;
-var resolutions = new Array(18);
-var matrixIds = new Array(18);
-for (var z = 0; z < 18; ++z) {
+var resolutions = new Array(14);
+var matrixIds = new Array(14);
+for (var z = 0; z < 14; ++z) {
   // generate resolutions and matrixIds arrays for this WMTS
   resolutions[z] = size / Math.pow(2, z);
   matrixIds[z] = z;
 }
 
+var attribution = new ol.Attribution({
+  html: 'Tiles &copy; <a href="http://services.arcgisonline.com/arcgis/rest/' +
+      'services/Demographics/USA_Population_Density/MapServer/">ArcGIS</a>'
+});
+
+
 var map = new ol.Map({
   layers: [
     new ol.layer.Tile({
@@ -28,25 +35,26 @@ var map = new ol.Map({
     new ol.layer.Tile({
       opacity: 0.7,
       source: new ol.source.WMTS({
-        url: 'http://demo-apollo.geospatial.intergraph.com/erdas-iws/ogc/wmts/',
-        layer: 'sampleiws_images_geodetic_worldgeodemo.ecw',
-        matrixSet: 'ogc:1.0:googlemapscompatible',
-        format: 'image/jpeg',
+        attributions: [attribution],
+        url: 'http://services.arcgisonline.com/arcgis/rest/' +
+            'services/Demographics/USA_Population_Density/MapServer/WMTS/',
+        layer: '0',
+        matrixSet: 'EPSG:3857',
+        format: 'image/png',
         projection: projection,
         tileGrid: new ol.tilegrid.WMTS({
           origin: ol.extent.getTopLeft(projectionExtent),
           resolutions: resolutions,
           matrixIds: matrixIds
         }),
-        extent: [-20037508.34, -20037508.34, 20037508.34, 20037508.34],
+        extent: projectionExtent,
         style: 'default'
       })
     })
   ],
   target: 'map',
   view: new ol.View2D({
-    center: [0, 0],
-    zoom: 0,
-    maxResolution: resolutions[1]
+    center: [-11158582, 4813697],
+    zoom: 4
   })
 });

examples/xyz.html

@@ -0,0 +1,51 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="chrome=1">
+    <meta name="viewport" content="initial-scale=1.0, user-scalable=no, width=device-width">
+    <link rel="stylesheet" href="../css/ol.css" type="text/css">
+    <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap.min.css" type="text/css">
+    <link rel="stylesheet" href="../resources/layout.css" type="text/css">
+    <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap-responsive.min.css" type="text/css">
+    <title>XYZ example</title>
+  </head>
+  <body>
+
+    <div class="navbar navbar-inverse navbar-fixed-top">
+      <div class="navbar-inner">
+        <div class="container">
+          <a class="brand" href="./"><img src="../resources/logo.png"> OpenLayers 3 Examples</a>
+        </div>
+      </div>
+    </div>
+
+    <div class="container-fluid">
+
+      <div class="row-fluid">
+        <div class="span12">
+          <div id="map" class="map"></div>
+        </div>
+      </div>
+
+      <div class="row-fluid">
+
+        <div class="span12">
+          <h4 id="title">XYZ example</h4>
+          <p id="shortdesc">Example of a XYZ source.</p>
+          <div id="docs">
+            <p>See the <a href="xyz.js" target="_blank">xyz.js source</a> for details on how this is done.</p>
+          </div>
+          <div id="tags">xyz</div>
+        </div>
+
+      </div>
+
+    </div>
+
+    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/example-behaviour.js" type="text/javascript"></script>
+    <script src="loader.js?id=xyz" type="text/javascript"></script>
+
+  </body>
+</html>

examples/xyz.js

@@ -0,0 +1,40 @@
+goog.require('ol.Attribution');
+goog.require('ol.Map');
+goog.require('ol.View2D');
+goog.require('ol.layer.Tile');
+goog.require('ol.source.OSM');
+goog.require('ol.source.XYZ');
+
+
+var attribution = new ol.Attribution({
+  html: 'Tiles &copy; <a href="http://maps.nls.uk/townplans/glasgow_1.html">' +
+      'National Library of Scotland</a>'
+});
+
+var map = new ol.Map({
+  target: 'map',
+  layers: [
+    new ol.layer.Tile({
+      source: new ol.source.OSM({
+        attributions: [
+          new ol.Attribution({
+            html: 'Tiles &copy; <a href="http://www.opencyclemap.org/">' +
+                'OpenCycleMap</a>'
+          }),
+          ol.source.OSM.DATA_ATTRIBUTION
+        ],
+        url: 'http://{a-c}.tile.opencyclemap.org/cycle/{z}/{x}/{y}.png'
+      })
+    }),
+    new ol.layer.Tile({
+      source: new ol.source.XYZ({
+        attributions: [attribution],
+        url: 'http://geo.nls.uk/maps/towns/glasgow1857/{z}/{x}/{-y}.png'
+      })
+    })
+  ],
+  view: new ol.View2D({
+    center: [-472202, 7530279],
+    zoom: 12
+  })
+});

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,32 +216,60 @@ 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}
+ * @todo api
+ */
+oli.interaction.DragAndDropEvent.prototype.file;
+
 
 /** @interface */
 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;
 
 
@@ -221,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/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,9 +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"
+    "jshint": "~2.4.4",
+    "jsdoc": "~3.3.0-alpha5",
+    "walk": "~2.3.1",
+    "fs-extra": "~0.8.1",
+    "nomnom": "~1.6.2",
+    "temp": "~0.7.0"
   }
 }

resources/example-behaviour.js

@@ -81,6 +81,6 @@ exampleNS.getRendererFromQueryString = function() {
   } else if ('renderer' in obj) {
     return [obj['renderer']];
   } else {
-    return ['webgl', 'canvas', 'dom'];
+    return undefined;
   }
 };

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

@@ -4,13 +4,14 @@ goog.provide('ol.animation');
 
 goog.require('ol.PreRenderFunction');
 goog.require('ol.ViewHint');
+goog.require('ol.coordinate');
 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;
@@ -45,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;
@@ -84,14 +85,16 @@ 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 = options.rotation;
+  var sourceRotation = goog.isDef(options.rotation) ? options.rotation : 0;
   var start = goog.isDef(options.start) ? options.start : goog.now();
   var duration = goog.isDef(options.duration) ? options.duration : 1000;
   var easing = goog.isDef(options.easing) ?
       options.easing : ol.easing.inAndOut;
+  var anchor = goog.isDef(options.anchor) ?
+      options.anchor : null;
 
   return (
       /**
@@ -106,9 +109,15 @@ ol.animation.rotate = function(options) {
         } else if (frameState.time < start + duration) {
           var delta = 1 - easing((frameState.time - start) / duration);
           var deltaRotation =
-              sourceRotation - frameState.view2DState.rotation;
+              (sourceRotation - frameState.view2DState.rotation) * delta;
           frameState.animate = true;
-          frameState.view2DState.rotation += delta * deltaRotation;
+          frameState.view2DState.rotation += deltaRotation;
+          if (!goog.isNull(anchor)) {
+            var center = frameState.view2DState.center;
+            ol.coordinate.sub(center, anchor);
+            ol.coordinate.rotate(center, deltaRotation);
+            ol.coordinate.add(center, anchor);
+          }
           frameState.viewHints[ol.ViewHint.ANIMATING] += 1;
           return true;
         } else {
@@ -121,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,13 +50,13 @@ 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) {
 
-  var options = opt_options || {};
+  var options = goog.isDef(opt_options) ? opt_options : {};
 
   var className = goog.isDef(options.className) ?
       options.className : 'ol-scale-line';
@@ -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) {
 
@@ -48,7 +48,6 @@ ol.control.Zoom = function(opt_options) {
   }, zoomInTipLabel);
   var inElement = goog.dom.createDom(goog.dom.TagName.BUTTON, {
     'class': className + '-in ol-has-tooltip',
-    'name' : 'ZoomIn',
     'type' : 'button'
   }, tTipZoomIn, zoomInLabel);
 
@@ -66,12 +65,11 @@ ol.control.Zoom = function(opt_options) {
   }, false);
 
   var tTipsZoomOut = goog.dom.createDom(goog.dom.TagName.SPAN, {
-    'role' : 'tooltip',
-    'type' : 'button'
+    'role' : 'tooltip'
   }, zoomOutTipLabel);
   var outElement = goog.dom.createDom(goog.dom.TagName.BUTTON, {
     'class': className + '-out  ol-has-tooltip',
-    'name' : 'ZoomOut'
+    'type' : 'button'
   }, tTipsZoomOut, zoomOutLabel);
 
   var outElementHandler = new ol.pointer.PointerEventHandler(outElement);

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);
@@ -182,6 +184,18 @@ ol.coordinate.scale = function(coordinate, s) {
 };
 
 
+/**
+ * @param {ol.Coordinate} coordinate Coordinate.
+ * @param {ol.Coordinate} delta Delta.
+ * @return {ol.Coordinate} Coordinate.
+ */
+ol.coordinate.sub = function(coordinate, delta) {
+  coordinate[0] -= delta[0];
+  coordinate[1] -= delta[1];
+  return coordinate;
+};
+
+
 /**
  * @param {ol.Coordinate} coord1 First coordinate.
  * @param {ol.Coordinate} coord2 Second coordinate.
@@ -210,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)) {
@@ -227,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);
@@ -239,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_;
@@ -149,13 +149,14 @@ ol.Feature.prototype.handleGeometryChanged_ = function() {
   if (goog.isDefAndNotNull(geometry)) {
     this.geometryChangeKey_ = goog.events.listen(geometry,
         goog.events.EventType.CHANGE, this.handleGeometryChange_, false, this);
+    this.dispatchChangeEvent();
   }
 };
 
 
 /**
  * @param {ol.geom.Geometry|undefined} geometry Geometry.
- * @todo stability experimental
+ * @todo api
  */
 ol.Feature.prototype.setGeometry = function(geometry) {
   this.set(this.geometryName_, geometry);
@@ -169,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;
@@ -180,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;
@@ -189,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(
@@ -210,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;
 
@@ -220,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({
@@ -260,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;
 
@@ -269,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();
@@ -350,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_;
@@ -113,8 +113,7 @@ ol.FeatureOverlay.prototype.handleFeatureChange_ = function() {
  * @private
  * @param {ol.CollectionEvent} collectionEvent Collection event.
  */
-ol.FeatureOverlay.prototype.handleFeaturesAdd_ =
-    function(collectionEvent) {
+ol.FeatureOverlay.prototype.handleFeaturesAdd_ = function(collectionEvent) {
   goog.asserts.assert(!goog.isNull(this.featureChangeListenerKeys_));
   var feature = /** @type {ol.Feature} */ (collectionEvent.element);
   this.featureChangeListenerKeys_[goog.getUid(feature).toString()] =
@@ -128,8 +127,7 @@ ol.FeatureOverlay.prototype.handleFeaturesAdd_ =
  * @private
  * @param {ol.CollectionEvent} collectionEvent Collection event.
  */
-ol.FeatureOverlay.prototype.handleFeaturesRemove_ =
-    function(collectionEvent) {
+ol.FeatureOverlay.prototype.handleFeaturesRemove_ = function(collectionEvent) {
   goog.asserts.assert(!goog.isNull(this.featureChangeListenerKeys_));
   var feature = /** @type {ol.Feature} */ (collectionEvent.element);
   var key = goog.getUid(feature).toString();
@@ -153,7 +151,7 @@ ol.FeatureOverlay.prototype.handleMapPostCompose_ = function(event) {
   }
   var resolution = event.frameState.view2DState.resolution;
   var vectorContext = event.vectorContext;
-  var i, ii, feature, styles;
+  var i, ii, styles;
   this.features_.forEach(function(feature) {
     styles = styleFunction(feature, resolution);
     if (!goog.isDefAndNotNull(styles)) {
@@ -163,13 +161,13 @@ ol.FeatureOverlay.prototype.handleMapPostCompose_ = function(event) {
     for (i = 0; i < ii; ++i) {
       vectorContext.drawFeature(feature, styles[i]);
     }
-  }, this);
+  });
 };
 
 
 /**
  * @param {ol.Feature} feature Feature.
- * @todo stability experimental
+ * @todo api
  */
 ol.FeatureOverlay.prototype.removeFeature = function(feature) {
   this.features_.remove(feature);
@@ -188,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_)) {
@@ -210,15 +208,11 @@ ol.FeatureOverlay.prototype.setFeatures = function(features) {
           this.handleFeaturesRemove_, false, this)
     ];
     this.featureChangeListenerKeys_ = {};
-    var featuresArray = features.getArray();
-    var i, ii = featuresArray.length;
-    var feature;
-    for (i = 0; i < ii; ++i) {
-      feature = featuresArray[i];
+    features.forEach(function(feature) {
       this.featureChangeListenerKeys_[goog.getUid(feature).toString()] =
           goog.events.listen(feature, goog.events.EventType.CHANGE,
           this.handleFeatureChange_, false, this);
-    }
+    }, this);
   }
   this.render_();
 };
@@ -226,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_)) {
@@ -250,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;
@@ -264,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_;
@@ -273,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} */
@@ -119,10 +118,12 @@ ol.format.GML.readFeatures_ = function(node, objectStack) {
   if (localName == 'FeatureCollection') {
     features = ol.xml.pushParseAndPop(null,
         ol.format.GML.FEATURE_COLLECTION_PARSERS, node, objectStack);
-  } else if (localName == 'featureMembers') {
+  } else if (localName == 'featureMembers' || localName == 'featureMember') {
     var parsers = {};
     var parsersNS = {};
-    parsers[featureType] = ol.xml.makeArrayPusher(ol.format.GML.readFeature_);
+    parsers[featureType] = (localName == 'featureMembers') ?
+        ol.xml.makeArrayPusher(ol.format.GML.readFeature_) :
+        ol.xml.makeReplacer(ol.format.GML.readFeature_);
     parsersNS[goog.object.get(context, 'featureNS')] = parsers;
     features = ol.xml.pushParseAndPop([], parsersNS, node, objectStack);
   }
@@ -138,6 +139,7 @@ ol.format.GML.readFeatures_ = function(node, objectStack) {
  */
 ol.format.GML.FEATURE_COLLECTION_PARSERS = {
   'http://www.opengis.net/gml': {
+    'featureMember': ol.xml.makeArrayPusher(ol.format.GML.readFeatures_),
     'featureMembers': ol.xml.makeReplacer(ol.format.GML.readFeatures_)
   }
 };

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;
 
@@ -378,8 +379,7 @@ ol.format.GPX.prototype.readFeature;
  */
 ol.format.GPX.prototype.readFeatureFromNode = function(node) {
   goog.asserts.assert(node.nodeType == goog.dom.NodeType.ELEMENT);
-  if (goog.array.indexOf(ol.format.GPX.NAMESPACE_URIS_, node.namespaceURI) ==
-      -1) {
+  if (!goog.array.contains(ol.format.GPX.NAMESPACE_URIS_, node.namespaceURI)) {
     return null;
   }
   var featureReader = ol.format.GPX.FEATURE_READER_[node.localName];
@@ -400,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;
 
@@ -409,8 +410,7 @@ ol.format.GPX.prototype.readFeatures;
  */
 ol.format.GPX.prototype.readFeaturesFromNode = function(node) {
   goog.asserts.assert(node.nodeType == goog.dom.NodeType.ELEMENT);
-  if (goog.array.indexOf(ol.format.GPX.NAMESPACE_URIS_, node.namespaceURI) ==
-      -1) {
+  if (!goog.array.contains(ol.format.GPX.NAMESPACE_URIS_, node.namespaceURI)) {
     return [];
   }
   if (node.localName == 'gpx') {
@@ -432,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;
 
@@ -793,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);
@@ -807,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;
 
@@ -156,6 +157,9 @@ ol.format.IGC.prototype.readFeatureFromText = function(text) {
       }
     }
   }
+  if (flatCoordinates.length === 0) {
+    return null;
+  }
   var lineString = new ol.geom.LineString(null);
   var layout = altitudeMode == ol.format.IGCZ.NONE ?
       ol.geom.GeometryLayout.XYM : ol.geom.GeometryLayout.XYZM;
@@ -173,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;
 
@@ -196,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;