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/drag-and-drop-image-vector.html

@@ -32,7 +32,7 @@
 
         <div class="span4">
           <h4 id="title">Drag-and-Drop image vector example</h4>
-          <p id="shortdesc">Example of using the drag-and-drop interaction with a <code>ol.source.ImageVector</code>. Drag and drop GPX, GeoJSON, IGC, KML, or TopoJSON files on to the map. Each file is rendered to an image on the client.</p>
+          <p id="shortdesc">Example of using the drag-and-drop interaction with a ol.source.ImageVector. Drag and drop GPX, GeoJSON, IGC, KML, or TopoJSON files on to the map. Each file is rendered to an image on the client.</p>
           <div id="docs">
             <p>See the <a href="drag-and-drop-image-vector.js" target="_blank">drag-and-drop-image-vector.js source</a> to see how this is done.</p>
           </div>

examples/drag-and-drop-image-vector.js

@@ -149,6 +149,6 @@ $(map.getViewport()).on('mousemove', function(evt) {
   displayFeatureInfo(pixel);
 });
 
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   displayFeatureInfo(evt.pixel);
 });

examples/drag-and-drop.js

@@ -145,6 +145,6 @@ $(map.getViewport()).on('mousemove', function(evt) {
   displayFeatureInfo(pixel);
 });
 
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   displayFeatureInfo(evt.pixel);
 });

examples/draw-features.html

@@ -32,7 +32,7 @@
 
         <div class="span12">
           <h4 id="title">Draw features example</h4>
-          <p id="shortdesc">Example of using the <code>ol.interaction.Draw</code> interaction.</p>
+          <p id="shortdesc">Example of using the ol.interaction.Draw interaction.</p>
           <form class="form-inline">
             <label>Geometry type &nbsp;</label>
               <select id="type">

examples/gpx.js

@@ -86,6 +86,6 @@ $(map.getViewport()).on('mousemove', function(evt) {
   displayFeatureInfo(pixel);
 });
 
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   displayFeatureInfo(evt.pixel);
 });

examples/icon.js

@@ -63,7 +63,7 @@ var popup = new ol.Overlay({
 map.addOverlay(popup);
 
 // display popup on click
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   var feature = map.forEachFeatureAtPixel(evt.pixel,
       function(feature, layer) {
         return feature;

examples/igc.html

@@ -32,8 +32,9 @@
 
         <div class="span4">
           <h4 id="title">IGC example</h4>
-          <p id="shortdesc">Example of tracks recorded from multiple paraglider flights on the same day, read from an IGC file. The five tracks contain a total of 49,707 unique coordinates. Zoom in to see more detail. The background layer is from <a href="http://www.opencyclemap.org/">OpenCycleMap</a>.</p>
+          <p id="shortdesc">Example of tracks recorded from multiple paraglider flights on the same day, read from an IGC file.</p>
           <div id="docs">
+            <p>The five tracks contain a total of 49,707 unique coordinates. Zoom in to see more detail. The background layer is from <a href="http://www.opencyclemap.org/">OpenCycleMap</a>.</p>
             <p>See the <a href="igc.js" target="_blank">igc.js source</a> to see how this is done.</p>
           </div>
           <input id="time" type="range" value="0" steps="1"></input>

examples/igc.js

@@ -125,7 +125,7 @@ $(map.getViewport()).on('mousemove', function(evt) {
   displaySnap(coordinate);
 });
 
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   displaySnap(evt.coordinate);
 });
 

examples/image-vector-layer.js

@@ -85,6 +85,6 @@ $(map.getViewport()).on('mousemove', function(evt) {
   displayFeatureInfo(pixel);
 });
 
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   displayFeatureInfo(evt.pixel);
 });

examples/kml-earthquakes.js

@@ -88,6 +88,6 @@ $(map.getViewport()).on('mousemove', function(evt) {
   displayFeatureInfo(map.getEventPixel(evt.originalEvent));
 });
 
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   displayFeatureInfo(evt.pixel);
 });

examples/kml-timezones.js

@@ -95,6 +95,6 @@ $(map.getViewport()).on('mousemove', function(evt) {
   displayFeatureInfo(map.getEventPixel(evt.originalEvent));
 });
 
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   displayFeatureInfo(evt.pixel);
 });

examples/kml.js

@@ -52,6 +52,6 @@ $(map.getViewport()).on('mousemove', function(evt) {
   displayFeatureInfo(pixel);
 });
 
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   displayFeatureInfo(evt.pixel);
 });

examples/localized-openstreetmap.html

@@ -32,8 +32,9 @@
 
         <div class="span12">
           <h4 id="title">Localized OpenStreetMap example</h4>
-          <p id="shortdesc">Example of a localized OpenStreetMap map with a custom tile server and a custom attribution. The base layer is <a href="http://www.opencyclemap.org/">OpenCycleMap</a> with an overlay from <a href="http://www.openseamap.org/">OpenSeaMap</a>. The OpenSeaMap tile server does not support <a href="http://enable-cors.org/">CORS</a> headers.</p>
+          <p id="shortdesc">Example of a localized OpenStreetMap map with a custom tile server and a custom attribution.</p>
           <div id="docs">
+            <p>The base layer is <a href="http://www.opencyclemap.org/">OpenCycleMap</a> with an overlay from <a href="http://www.openseamap.org/">OpenSeaMap</a>. The OpenSeaMap tile server does not support <a href="http://enable-cors.org/">CORS</a> headers.</p>
             <p>See the <a href="localized-openstreetmap.js" target="_blank">localized-openstreetmap.js source</a> to see how this is done.</p>
           </div>
           <div id="tags">cors, localized-openstreetmap, openseamap, openstreetmap</div>

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/overlay.js

@@ -45,7 +45,7 @@ var popup = new ol.Overlay({
 });
 map.addOverlay(popup);
 
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   var element = popup.getElement();
   var coordinate = evt.coordinate;
   var hdms = ol.coordinate.toStringHDMS(ol.proj.transform(

examples/popup.js

@@ -60,7 +60,7 @@ var map = new ol.Map({
 /**
  * Add a click handler to the map to render the popup.
  */
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   var coordinate = evt.coordinate;
   var hdms = ol.coordinate.toStringHDMS(ol.proj.transform(
       coordinate, 'EPSG:3857', 'EPSG:4326'));

examples/static-image.html

@@ -32,8 +32,9 @@
 
         <div class="span12">
           <h4 id="title">Static image example</h4>
-          <p id="shortdesc">Example of a static image layer. Source: <a href="http://xkcd.com/256/">xkcd.com/256/</a></p>
+          <p id="shortdesc">Example of a static image layer.</p>
           <div id="docs">
+            <p>Source: <a href="http://xkcd.com/256/">xkcd.com/256/</a></p>
             <p>See the <a href="static-image.js" target="_blank">static-image.js source</a> to see how this is done.</p>
           </div>
           <div id="tags">static image, xkcd</div>

examples/synthetic-points.js

@@ -94,7 +94,7 @@ $(map.getViewport()).on('mousemove', function(evt) {
   displaySnap(coordinate);
 });
 
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   displaySnap(evt.coordinate);
 });
 

examples/tile-vector.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>Tile vector 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" style="background: white;"></div>
+        </div>
+      </div>
+
+      <div class="row-fluid">
+
+        <div class="span12">
+          <h4 id="title">Tile vector example</h4>
+          <p id="shortdesc">Example of vector tiles from openstreetmap.us.</p>
+          <div id="docs">
+            <p>See the <a href="tile-vector.js" target="_blank">tile-vector.js source</a> to see how this is done.</p>
+          </div>
+          <div id="tags">tile-vector, openstreetmap</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=tile-vector" type="text/javascript"></script>
+
+  </body>
+</html>

examples/tile-vector.js

@@ -0,0 +1,85 @@
+goog.require('ol.Map');
+goog.require('ol.View2D');
+goog.require('ol.format.TopoJSON');
+goog.require('ol.layer.Vector');
+goog.require('ol.proj');
+goog.require('ol.source.TileVector');
+goog.require('ol.style.Fill');
+goog.require('ol.style.Stroke');
+goog.require('ol.style.Style');
+goog.require('ol.tilegrid.XYZ');
+
+var waterLayer = new ol.layer.Vector({
+  source: new ol.source.TileVector({
+    format: new ol.format.TopoJSON({
+      defaultProjection: 'EPSG:4326'
+    }),
+    projection: 'EPSG:3857',
+    tileGrid: new ol.tilegrid.XYZ({
+      maxZoom: 19
+    }),
+    url: 'http://{a-c}.tile.openstreetmap.us/' +
+        'vectiles-water-areas/{z}/{x}/{y}.topojson'
+  }),
+  style: new ol.style.Style({
+    fill: new ol.style.Fill({
+      color: '#9db9e8'
+    })
+  })
+});
+
+var roadStyleCache = {};
+var roadLayer = new ol.layer.Vector({
+  source: new ol.source.TileVector({
+    format: new ol.format.TopoJSON({
+      defaultProjection: 'EPSG:4326'
+    }),
+    projection: 'EPSG:3857',
+    tileGrid: new ol.tilegrid.XYZ({
+      maxZoom: 19
+    }),
+    url: 'http://{a-c}.tile.openstreetmap.us/' +
+        'vectiles-highroad/{z}/{x}/{y}.topojson'
+  }),
+  style: function(feature, resolution) {
+    var kind = feature.get('kind');
+    var railway = feature.get('railway');
+    var sort_key = feature.get('sort_key');
+    var styleKey = kind + '/' + railway + '/' + sort_key;
+    var styleArray = roadStyleCache[styleKey];
+    if (!styleArray) {
+      var color, width;
+      if (railway) {
+        color = '#7de';
+        width = 1;
+      } else {
+        color = {
+          'major_road': '#776',
+          'minor_road': '#ccb',
+          'highway': '#f39'
+        }[kind];
+        width = kind == 'highway' ? 1.5 : 1;
+      }
+      styleArray = [new ol.style.Style({
+        stroke: new ol.style.Stroke({
+          color: color,
+          width: width
+        }),
+        zIndex: sort_key
+      })];
+      roadStyleCache[styleKey] = styleArray;
+    }
+    return styleArray;
+  }
+});
+
+var map = new ol.Map({
+  layers: [waterLayer, roadLayer],
+  renderer: 'canvas',
+  target: document.getElementById('map'),
+  view: new ol.View2D({
+    center: ol.proj.transform([-74.0064, 40.7142], 'EPSG:4326', 'EPSG:3857'),
+    maxZoom: 19,
+    zoom: 14
+  })
+});

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-layer.js

@@ -122,6 +122,6 @@ $(map.getViewport()).on('mousemove', function(evt) {
   displayFeatureInfo(pixel);
 });
 
-map.on('singleclick', function(evt) {
+map.on('click', function(evt) {
   displayFeatureInfo(evt.pixel);
 });

examples/vector-osm.html

@@ -32,11 +32,11 @@
 
         <div class="span4">
           <h4 id="title">OSM XML example</h4>
-          <p id="shortdesc">Example of using the OSM XML source.</p>
+          <p id="shortdesc">Example of using the OSM XML source.  Vector data is loaded dynamically from a server using a tiling strategy.</p>
           <div id="docs">
             <p>See the <a href="vector-osm.js" target="_blank">vector-osm.js source</a> to see how this is done.</p>
           </div>
-          <div id="tags">vector, osm, xml</div>
+          <div id="tags">vector, osm, xml, loading, server</div>
         </div>
         <div class="span4 offset4">
           <div id="info" class="alert alert-success">

examples/vector-osm.js

@@ -1,13 +1,17 @@
 goog.require('ol.Map');
 goog.require('ol.View2D');
+goog.require('ol.format.OSMXML');
 goog.require('ol.layer.Tile');
 goog.require('ol.layer.Vector');
+goog.require('ol.loadingstrategy');
+goog.require('ol.proj');
 goog.require('ol.source.BingMaps');
-goog.require('ol.source.OSMXML');
+goog.require('ol.source.ServerVector');
 goog.require('ol.style.Circle');
 goog.require('ol.style.Fill');
 goog.require('ol.style.Stroke');
 goog.require('ol.style.Style');
+goog.require('ol.tilegrid.XYZ');
 
 var styles = {
   'amenity': {
@@ -83,9 +87,21 @@ var styles = {
   }
 };
 
-var vectorSource = new ol.source.OSMXML({
-  projection: 'EPSG:3857',
-  url: 'data/osm/map.osm'
+var vectorSource = new ol.source.ServerVector({
+  format: new ol.format.OSMXML(),
+  loader: function(extent, resolution, projection) {
+    var transform = ol.proj.getTransform(projection, 'EPSG:4326');
+    var epsg4326Extent = transform(extent, []);
+    var url = 'http://overpass-api.de/api/xapi?map?bbox=' +
+        epsg4326Extent.join(',');
+    $.ajax(url).then(function(response) {
+      vectorSource.addFeatures(vectorSource.readFeatures(response));
+    });
+  },
+  strategy: ol.loadingstrategy.createTile(new ol.tilegrid.XYZ({
+    maxZoom: 19
+  })),
+  projection: 'EPSG:3857'
 });
 
 var vector = new ol.layer.Vector({
@@ -117,6 +133,7 @@ var map = new ol.Map({
   target: document.getElementById('map'),
   view: new ol.View2D({
     center: [739218, 5906096],
+    maxZoom: 19,
     zoom: 17
   })
 });

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/bootstrap.js

@@ -6,16 +6,15 @@
  */
 
 
-
 /**
- * @param {string|Object.<string,*>=} option
+ * @param {string|Object.<string,*>=} opt_option
  * @return {!jQuery}
  */
-jQuery.prototype.popover = function(option) {};
+jQuery.prototype.popover = function(opt_option) {};
 
 
 /**
- * @param {string|Object.<string,*>=} option
+ * @param {string|Object.<string,*>=} opt_option
  * @return {!jQuery}
  */
-jQuery.prototype.tooltip = function(option) {};
+jQuery.prototype.tooltip = function(opt_option) {};

externs/closure-compiler.js

@@ -10,30 +10,37 @@
 
 // @see https://code.google.com/p/closure-compiler/issues/detail?id=1060
 
+
 /** @type {Date} */
 HTMLInputElement.prototype.valueAsDate;
 
+
 /** @type {number} */
 HTMLInputElement.prototype.valueAsNumber;
 
 
 // @see https://code.google.com/p/closure-compiler/issues/detail?id=1084
 
+
 /** @type {?number} */
 DeviceRotationRate.prototype.alpha;
 
+
 /** @type {?number} */
 DeviceRotationRate.prototype.beta;
 
+
 /** @type {?number} */
 DeviceRotationRate.prototype.gamma;
 
 
 // @see https://code.google.com/p/closure-compiler/issues/detail?id=1088
 
+
 /** @type {?number} */
 DeviceOrientationEvent.prototype.webkitCompassAccuracy;
 
+
 /** @type {?number} */
 DeviceOrientationEvent.prototype.webkitCompassHeading;
 
@@ -41,15 +48,19 @@ DeviceOrientationEvent.prototype.webkitCompassHeading;
 // IE 11 fullscreen API
 // http://msdn.microsoft.com/en-us/library/ie/dn265028(v=vs.85).aspx
 
+
 /** @return {void} */
 Element.prototype.msRequestFullscreen = function() {};
 
+
 /** @return {void} */
 Element.prototype.msExitFullscreen = function() {};
 
+
 /** @type {boolean} */
 Document.prototype.msFullscreenEnabled;
 
+
 /** @type {Element} */
 Document.prototype.msFullscreenElement;
 
@@ -57,17 +68,22 @@ Document.prototype.msFullscreenElement;
 /** @type {number} */
 Touch.prototype.force;
 
+
 /** @type {number} */
 Touch.prototype.radiusX;
 
+
 /** @type {number} */
 Touch.prototype.radiusY;
 
+
 /** @type {number} */
 Touch.prototype.webkitForce;
 
+
 /** @type {number} */
 Touch.prototype.webkitRadiusX;
 
+
 /** @type {number} */
 Touch.prototype.webkitRadiusY;

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,10 +39,15 @@ oli.DragBoxEvent.prototype.coordinate;
 oli.DrawEvent;
 
 
-/** @type {ol.Feature} */
+/**
+ * The feature being drawn.
+ * @type {ol.Feature}
+ * @todo api
+ */
 oli.DrawEvent.prototype.feature;
 
 
+
 /** @interface */
 oli.FrameState;
 
@@ -64,19 +76,22 @@ oli.FrameState.prototype.focus;
 oli.FrameState.prototype.index;
 
 
-/** @type {Array.<ol.layer.Layer>} */
-oli.FrameState.prototype.layersArray;
-
-
 /** @type {Object.<number, ol.layer.LayerState>} */
 oli.FrameState.prototype.layerStates;
 
 
+/** @type {Array.<ol.layer.LayerState>} */
+oli.FrameState.prototype.layerStatesArray;
+
+
 /** @type {Object.<string, string>} */
 oli.FrameState.prototype.logos;
 
 
-/** @type {number} */
+/**
+ * @type {number}
+ * @todo api
+ */
 oli.FrameState.prototype.pixelRatio;
 
 
@@ -100,7 +115,10 @@ oli.FrameState.prototype.skippedFeatureUids_;
 oli.FrameState.prototype.tileQueue;
 
 
-/** @type {number} */
+/**
+ * @type {number}
+ * @todo api
+ */
 oli.FrameState.prototype.time;
 
 
@@ -108,7 +126,10 @@ oli.FrameState.prototype.time;
 oli.FrameState.prototype.usedTiles;
 
 
-/** @type {oli.View2DState} */
+/**
+ * @type {oli.View2DState}
+ * @todo api
+ */
 oli.FrameState.prototype.view2DState;
 
 
@@ -120,6 +141,7 @@ oli.FrameState.prototype.viewHints;
 oli.FrameState.prototype.wantedTiles;
 
 
+
 /** @interface */
 oli.ObjectEvent;
 
@@ -133,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;
 
 
@@ -185,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;
 
 
@@ -219,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/proj4js.js

@@ -89,4 +89,4 @@ Proj4js.Proj.prototype.to_meter;
  * @param {Proj4js.Point|{x:number, y:number}} point
  * @return {Proj4js.Point}
  */
-Proj4js.transform = function(source, dest, point) {};
+Proj4js.transform = function(source, dest, point) {return null;};

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) {
+  // ...
+};
+```

externs/vbarray.js

@@ -4,6 +4,7 @@
  */
 
 
+
 /**
  * FIXME check argument type
  * @constructor
@@ -15,7 +16,7 @@ var VBArray = function(safeArray) {};
 /**
  * @return {number}
  */
-VBArray.prototype.dimensions = function() {};
+VBArray.prototype.dimensions = function() {return 0;};
 
 
 /**
@@ -35,7 +36,7 @@ VBArray.prototype.lbound = function(opt_dimension) {};
 /**
  * @return {Array.<number>}
  */
-VBArray.prototype.toArray = function() {};
+VBArray.prototype.toArray = function() {return null;};
 
 
 /**

externs/webgl-debug.js

@@ -25,7 +25,8 @@ var WebGLDebugLostContextSimulatingCanvas = function() {};
  * @nosideeffects
  * @return {number}
  */
-WebGLDebugLostContextSimulatingCanvas.prototype.getNumCalls = function() {};
+WebGLDebugLostContextSimulatingCanvas.prototype.getNumCalls =
+    function() {return NaN;};
 
 
 /**
@@ -63,7 +64,7 @@ var WebGLDebugUtils = {};
  * @param {number} value
  * @return {string}
  */
-WebGLDebugUtils.glEnumToString = function(value) {};
+WebGLDebugUtils.glEnumToString = function(value) {return '';};
 
 
 /**
@@ -72,7 +73,9 @@ WebGLDebugUtils.glEnumToString = function(value) {};
  * @param {Array} args Args.
  * @return {string} String.
  */
-WebGLDebugUtils.glFunctionArgsToString = function(functionName, args) {};
+WebGLDebugUtils.glFunctionArgsToString = function(functionName, args) {
+  return '';
+};
 
 
 /**
@@ -85,7 +88,9 @@ WebGLDebugUtils.init = function(ctx) {};
  * @param {HTMLCanvasElement} canvas
  * @return {WebGLDebugLostContextSimulatingCanvas}
  */
-WebGLDebugUtils.makeLostContextSimulatingCanvas = function(canvas) {};
+WebGLDebugUtils.makeLostContextSimulatingCanvas = function(canvas) {
+  return null;
+};
 
 
 /**
@@ -95,4 +100,4 @@ WebGLDebugUtils.makeLostContextSimulatingCanvas = function(canvas) {};
  * @return {WebGLDebugRenderingContext}
  */
 WebGLDebugUtils.makeDebugContext =
-    function(context, opt_onErrorFunc, opt_onFunc) {};
+    function(context, opt_onErrorFunc, opt_onFunc) {return null;};

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) {
 
@@ -74,13 +74,13 @@ ol.control.Attribution.prototype.getSourceAttributions =
     function(frameState) {
   var i, ii, j, jj, tileRanges, source, sourceAttribution,
       sourceAttributionKey, sourceAttributions, sourceKey;
-  var layers = frameState.layersArray;
+  var layerStatesArray = frameState.layerStatesArray;
   /** @type {Object.<string, ol.Attribution>} */
   var attributions = goog.object.clone(frameState.attributions);
   /** @type {Object.<string, ol.Attribution>} */
   var hiddenAttributions = {};
-  for (i = 0, ii = layers.length; i < ii; i++) {
-    source = layers[i].getSource();
+  for (i = 0, ii = layerStatesArray.length; i < ii; i++) {
+    source = layerStatesArray[i].layer.getSource();
     sourceKey = goog.getUid(source).toString();
     sourceAttributions = source.getAttributions();
     if (goog.isNull(sourceAttributions)) {

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