Merge pull request #2641 from elemoine/sphere

Add @api to ol.Sphere

README.md

@@ -2,9 +2,9 @@
 
 [![Travis CI Status](https://secure.travis-ci.org/openlayers/ol3.png)](http://travis-ci.org/#!/openlayers/ol3)
 
-Welcome to [OpenLayers 3](http://ol3js.org/)!
+Welcome to [OpenLayers 3](http://openlayers.org/)!
 
-Check out the [hosted examples](http://ol3js.org/en/master/examples/), the [workshop](http://ol3js.org/ol3-workshop/) or poke around the evolving [API docs](http://ol3js.org/en/master/apidoc/).
+Check out the [hosted examples](http://openlayers.org/en/master/examples/), the [workshop](http://openlayers.org/ol3-workshop/) or poke around the evolving [API docs](http://openlayers.org/en/master/apidoc/).
 
 Please don't ask questions in the github issue tracker but use [the mailing list](https://groups.google.com/forum/#!forum/ol3-dev) instead.
 

bin/loader_hosted_examples.js

@@ -1,13 +1,13 @@
 /**
- * Loader to add ol.css, ol.js and the example-specific js file to the
- * documents.
- *
  * This loader is used for the hosted examples. It is used in place of the
  * development loader (examples/loader.js).
  *
- * The ol.js, ol-debug.js, and ol-deps.js scripts are built by OL3's
- * build.py script. They are located in the ../build/ directory, relative to
- * this script.
+ * The loader loads ol.js and the example's script in "production" mode; it
+ * loads Closure Library's base.js, ol-deps.js, the example's "goog.require"
+ * script, and the example's script in "development" mode.
+ *
+ * The ol.js and ol-deps.js scripts are built by OL3's build.py script.
+ * They are located in the ../build/ directory, relative to this script.
  *
  * The script must be named loader.js.
  *

build.py

@@ -101,6 +101,10 @@ SPEC = [path
         for path in ifind('test/spec')
         if path.endswith('.js')]
 
+TASKS = [path
+         for path in ifind('tasks')
+         if path.endswith('.js')]
+
 SRC = [path
        for path in ifind('src/ol')
        if path.endswith('.js')
@@ -123,14 +127,14 @@ def report_sizes(t):
 virtual('default', 'build')
 
 
-virtual('ci', 'lint', 'jshint', 'build', 'test',
+virtual('ci', 'lint', 'build', 'test',
     'build/examples/all.combined.js', 'check-examples', 'apidoc')
 
 
 virtual('build', 'build/ol.css', 'build/ol.js', 'build/ol-debug.js')
 
 
-virtual('check', 'lint', 'jshint', 'test')
+virtual('check', 'lint', 'build/ol.js', 'test')
 
 
 virtual('todo', 'fixme')
@@ -141,15 +145,15 @@ def build_ol_css(t):
     t.output('%(CLEANCSS)s', 'css/ol.css')
 
 
-@target('build/ol.js', SRC, SHADER_SRC, 'buildcfg/ol.json')
+@target('build/ol.js', SRC, SHADER_SRC, 'config/ol.json')
 def build_ol_new_js(t):
-    t.run('node', 'tasks/build.js', 'buildcfg/ol.json', 'build/ol.js')
+    t.run('node', 'tasks/build.js', 'config/ol.json', 'build/ol.js')
     report_sizes(t)
 
 
-@target('build/ol-debug.js', SRC, SHADER_SRC, 'buildcfg/ol-debug.json')
+@target('build/ol-debug.js', SRC, SHADER_SRC, 'config/ol-debug.json')
 def build_ol_debug_js(t):
-    t.run('node', 'tasks/build.js', 'buildcfg/ol-debug.json', 'build/ol-debug.js')
+    t.run('node', 'tasks/build.js', 'config/ol-debug.json', 'build/ol-debug.js')
     report_sizes(t)
 
 
@@ -196,9 +200,9 @@ def examples_examples_list_js(t):
 
 
 @target('build/examples/all.combined.js', 'build/examples/all.js',
-        SRC, SHADER_SRC, 'buildcfg/examples-all.json')
+        SRC, SHADER_SRC, 'config/examples-all.json')
 def build_examples_all_combined_js(t):
-    t.run('node', 'tasks/build.js', 'buildcfg/examples-all.json',
+    t.run('node', 'tasks/build.js', 'config/examples-all.json',
           'build/examples/all.combined.js')
     report_sizes(t)
 
@@ -214,7 +218,7 @@ def examples_star_json(name, match):
         # 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
+        # Note that we use the proper way in config/examples-all.json, which
         # is only used to check the examples code using the compiler.
         content = json.dumps({
           "exports": [],
@@ -307,7 +311,7 @@ def serve(t):
 
 
 virtual('lint', 'build/lint-timestamp', 'build/check-requires-timestamp',
-    'build/check-whitespace-timestamp')
+    'build/check-whitespace-timestamp', 'jshint')
 
 
 @target('build/lint-timestamp', SRC, EXAMPLES_SRC, SPEC, precious=True)
@@ -322,7 +326,7 @@ def build_lint_src_timestamp(t):
 
 virtual('jshint', 'build/jshint-timestamp')
 
-@target('build/jshint-timestamp', SRC, EXAMPLES_SRC, SPEC,
+@target('build/jshint-timestamp', SRC, EXAMPLES_SRC, SPEC, TASKS,
         precious=True)
 def build_jshint_timestamp(t):
     t.run(variables.JSHINT, '--verbose', t.newer(t.dependencies))
@@ -529,9 +533,10 @@ virtual('apidoc', 'build/jsdoc-%(BRANCH)s-timestamp' % vars(variables))
 
 
 @target('build/jsdoc-%(BRANCH)s-timestamp' % vars(variables), 'host-resources',
-        SRC, SHADER_SRC, ifind('apidoc/template'))
+        SRC, SHADER_SRC, ifind('config/jsdoc/api/template'))
 def jsdoc_BRANCH_timestamp(t):
-    t.run('%(JSDOC)s', 'apidoc/index.md', '-c', 'apidoc/conf.json',
+    t.run('%(JSDOC)s', 'config/jsdoc/api/index.md',
+          '-c', 'config/jsdoc/api/conf.json',
           '-d', 'build/hosted/%(BRANCH)s/apidoc')
     t.touch()
 

buildcfg/jsdoc/info/publish.js

@@ -1,59 +0,0 @@
-/**
- * @fileoverview Generates JSON output based on exportable symbols (those with
- * an api tag) and boolean defines (with a define tag and a default value).
- */
-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 or define (excluding enums,
-  // typedefs and events)
-  var docs = data(
-      [{define: {isObject: true}}, {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 = [];
-  var defines = [];
-  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;
-  }).forEach(function(doc) {
-    if (doc.define) {
-      defines.push({
-        name: doc.longname,
-        description: doc.description,
-        path: path.join(doc.meta.path, doc.meta.filename),
-        default: doc.define.default
-      });
-    } else {
-      symbols.push({
-        name: doc.longname,
-        kind: doc.kind,
-        description: doc.classdesc || doc.description,
-        path: path.join(doc.meta.path, doc.meta.filename)
-      });
-    }
-  });
-
-  process.stdout.write(
-      JSON.stringify({symbols: symbols, defines: defines}, null, 2));
-
-};

buildcfg/readme.md

@@ -1,3 +0,0 @@
-# Build configs
-
-This directory includes configuration files (json) for the build scripts in tasks/.

config/jsdoc/api/conf.json

@@ -1,7 +1,7 @@
 {
     "opts": {
         "recurse": true,
-        "template": "apidoc/template"
+        "template": "config/jsdoc/api/template"
     },
     "tags": {
         "allowUnknownTags": true
@@ -17,12 +17,12 @@
     },
     "plugins": [
         "node_modules/jsdoc/plugins/markdown",
-        "apidoc/plugins/inheritdoc",
-        "apidoc/plugins/interface",
-        "apidoc/plugins/typedefs",
-        "apidoc/plugins/events",
-        "apidoc/plugins/observable",
-        "apidoc/plugins/api"
+        "config/jsdoc/api/plugins/inheritdoc",
+        "config/jsdoc/api/plugins/interface",
+        "config/jsdoc/api/plugins/typedefs",
+        "config/jsdoc/api/plugins/events",
+        "config/jsdoc/api/plugins/observable",
+        "config/jsdoc/api/plugins/api"
     ],
     "markdown": {
         "parser": "gfm"

config/jsdoc/api/plugins/observable.js

@@ -34,6 +34,9 @@ exports.handlers = {
         } else if (doclet.name.indexOf('set') === 0) {
           observable.readonly = false;
         }
+        if (doclet.stability) {
+          observable.stability = doclet.stability;
+        }
         if (!cls.observables) {
           cls.observables = [];
         }

config/jsdoc/api/plugins/typedefs.js

@@ -28,6 +28,10 @@ exports.handlers = {
   newDoclet: function(e) {
     var doclet = e.doclet;
     if (doclet.meta.filename == 'olx.js') {
+      // do nothing if not marked @api
+      if (!doclet.stability) {
+        return;
+      }
       if (doclet.kind == 'typedef') {
         lastOlxTypedef = doclet;
         olxTypes[doclet.longname] = [];

config/jsdoc/api/template/static/scripts/main.js

@@ -52,4 +52,13 @@ $(function () {
 
     $(window).on('resize', _onResize);
     _onResize();
+
+    // show/hide unstable items
+    var unstable = $('.unstable');
+    var stabilityToggle = $('#stability-toggle');
+    stabilityToggle.change(function() {
+        unstable.toggle(!this.checked);
+        return false;
+    });
+    unstable.toggle(!stabilityToggle[0].checked);
 });

config/jsdoc/api/template/static/styles/jaguar.css

@@ -183,6 +183,10 @@ li {
   font-size: 0.8em;
   padding: 2px 4px;
 }
+td.description span.stability {
+  float: left;
+  margin-right: 0.5em;
+}
 span.type-signature.static {
   margin-right: 3px;
 }
@@ -282,7 +286,6 @@ span.type-signature.static {
   width: 110px;
 }
 .main table .type {
-  width: 60px;
   color: #aaa;
   font-size: 12px;
 }
@@ -369,3 +372,12 @@ footer {
 .main .readme table ul li {
   margin-bottom: 0;
 }
+.unstable {
+  display: none;
+}
+#stability {
+  color: white;
+  position: absolute;
+  top: 1em;
+  right: 8em;
+}

config/jsdoc/api/template/tmpl/layout.tmpl

@@ -18,8 +18,11 @@
 <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</a>
+      <a class="brand" href="/"><img src="../resources/logo.png" width="40"> OpenLayers 3</a>
       <a class="brand" href="index.html">API Documentation</a>
+      <label id="stability">
+        <input type="checkbox" id="stability-toggle" checked> Stable Only
+      </label>
     </div>
   </div>
 </div>

config/jsdoc/api/template/tmpl/members.tmpl

@@ -9,7 +9,7 @@ if (data.type && data.type.names) {
     });
 }
 ?>
-<dt>
+<dt class="<?js= (data.stability && data.stability !== 'stable') ? 'unstable' : '' ?>">
     <div class="nameContainer">
         <h4 class="name" id="<?js= id ?>">
             <?js= data.attribs + (data.scope === 'static' ? longname : name)  + typeSignature ?>
@@ -20,7 +20,7 @@ if (data.type && data.type.names) {
     <p class="summary"><?js= summary ?></p>
     <?js } ?>
 </dt>
-<dd>
+<dd class="<?js= (data.stability && data.stability !== 'stable') ? 'unstable' : '' ?>">
     <?js if (data.description) { ?>
     <div class="description">
         <?js= data.description ?>

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

@@ -2,7 +2,7 @@
 var data = obj;
 var self = this;
 ?>
-<dt>
+<dt class="<?js= (data.stability && data.stability !== 'stable') ? 'unstable' : '' ?>">
     <div class="nameContainer<?js if (data.inherited) { ?> inherited<?js } ?>">
         <?js if (data.stability || kind !== 'class') { ?>
         <h4 class="name" id="<?js= id ?>">
@@ -23,7 +23,7 @@ var self = this;
     <p class="summary"><?js= summary ?></p>
     <?js } ?>
 </dt>
-<dd>
+<dd class="<?js= (data.stability && data.stability !== 'stable') ? 'unstable' : '' ?>">
     
     <?js if (data.description) { ?>
     <div class="description">
@@ -67,7 +67,7 @@ var self = this;
               description = eventDoclet.description.replace(/<[^>]*>/g, '');
             }
         ?>
-        <li>
+        <li class="<?js= (eventDoclet || data).stability !== 'stable' ? 'unstable' : '' ?>">
             <code><?js= self.linkto(f, type) ?></code>
             <?js if (eventClassName) {
               var eventClass = self.find({longname: eventClassName})[0];

config/jsdoc/api/template/tmpl/navigation.tmpl

@@ -39,7 +39,9 @@ var self = this;
             <?js
                 item.typedefs.forEach(function (v) {
             ?>
-                <li data-name="<?js= v.longname ?>"><?js= self.linkto(v.longname, v.name) ?></li>
+                <li data-name="<?js= v.longname ?>" class="<?js= v.stability !== 'stable' ? 'unstable' : ''?>">
+                    <?js= self.linkto(v.longname, v.name) ?>
+                </li>
             <?js
                 });
             }
@@ -54,36 +56,9 @@ var self = this;
 
                 item.methods.forEach(function (v) {
             ?>
-                <li data-name="<?js= v.longname ?>"><?js= self.linkto(v.longname, v.name) ?></li>
-            <?js
-                });
-            }
-            ?>
-            </ul>
-            <ul class="fires itemMembers">
-            <?js
-            if (item.fires && item.fires.length) {
-            ?>
-            <span class="subtitle">Fires</span>
-            <?js
-                item.fires.forEach(function (v) {
-                    v = self.find({longname: v})[0] || {longname: v, name: v.split(/#?event:/)[1]};
-            ?>
-                <li data-name="<?js= v.longname ?>"><?js= self.linkto(v.longname, v.name) ?></li>
-            <?js
-                });
-            }
-            ?>
-            </ul>
-            <ul class="events itemMembers">
-            <?js
-            if (item.events.length) {
-            ?>
-            <span class="subtitle">Events</span>
-            <?js
-                item.events.forEach(function (v) {
-            ?>
-                <li data-name="<?js= v.longname ?>"><?js= self.linkto(v.longname, v.name) ?></li>
+                <li data-name="<?js= v.longname ?>" class="<?js= v.stability !== 'stable' ? 'unstable' : ''?>">
+                    <?js= self.linkto(v.longname, v.name) ?>
+                </li>
             <?js
                 });
             }

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

@@ -21,7 +21,7 @@
         var setter = prop.readonly ? 'no' : 'yes';
   ?>
 
-    <tr>
+    <tr class="<?js= prop.stability !== 'stable' ? 'unstable' : '' ?>">
       <td class="name"><code><?js= prop.name ?></code></td>
       <td class="type">
       <?js if (prop.type && prop.type.names) {?>

config/jsdoc/api/template/tmpl/params.tmpl

@@ -71,7 +71,7 @@
 	        if (!param) { return; }
 	?>
 	
-        <tr>
+        <tr class="<?js= (param.stability && param.stability !== 'stable') ? 'unstable' : '' ?>">
             <?js if (params.hasName) {?>
                 <td class="name"><code><?js= param.name.replace(/^opt_/, "") ?></code></td>
             <?js } ?>
@@ -93,17 +93,8 @@
             <?js } ?>
             
             <td<?js= (param.subparams ? ' colspan=' + colspan : ' ') ?> class="description last">
-                <?js if (params.hasAttributes) {?>
-                    <?js if (param.optional) { ?>
-                        <span class="optional">optional</span>
-                    <?js } ?>
-                    <?js if (param.nullable) { ?>
-                        <span class="nullable">nullable</span>
-                    <?js } ?>
-              
-                    <?js if (param.variable) { ?>
-                        <span class="repeatable">repeatable</span>
-                    <?js } ?>
+                <?js if (param.stability) { ?>
+                    <?js= self.partial('stability.tmpl', param) ?>
                 <?js } ?>
                 <?js= param.description ?><?js if (param.subparams) { ?>
                 <?js= self.partial('params.tmpl', param.subparams) ?>

config/jsdoc/info/conf.json

@@ -1,7 +1,7 @@
 {
     "opts": {
         "recurse": true,
-        "template": "buildcfg/jsdoc/info"
+        "template": "config/jsdoc/info"
     },
     "tags": {
         "allowUnknownTags": true
@@ -10,7 +10,8 @@
         "includePattern": "\\.js$"
     },
     "plugins": [
-        "buildcfg/jsdoc/info/api-plugin",
-        "buildcfg/jsdoc/info/define-plugin"
+        "config/jsdoc/info/api-plugin",
+        "config/jsdoc/info/define-plugin",
+        "config/jsdoc/info/virtual-plugin"
     ]
 }

config/jsdoc/info/publish.js

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview Generates JSON output based on exportable symbols (those with
+ * an api tag) and boolean defines (with a define tag and a default value).
+ */
+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) {
+
+  function getTypes(data) {
+    var types = [];
+    data.forEach(function(name) {
+      types.push(name.replace(/^function$/, 'Function'));
+    });
+    return types;
+  }
+
+  function replaceUnknownTypes(item) {
+    item.types.forEach(function(type, index) {
+      if (!(type in names)) {
+        item.types[index] = '*';
+      }
+    });
+  }
+
+  // get all doclets with the "api" property or define (excluding events) or
+  // with olx namespace
+  var classes = {};
+  var docs = data(
+      [
+        {define: {isObject: true}},
+        function() {
+          if (this.kind == 'class') {
+            if (!('extends' in this) || typeof this.api == 'string') {
+              classes[this.longname] = this;
+              return true;
+            }
+          }
+          return (typeof this.api == 'string' ||
+              this.meta && (/[\\\/]externs$/).test(this.meta.path));
+        }
+      ],
+      {kind: {'!is': 'file'}},
+      {kind: {'!is': 'event'}}).get();
+
+  // get symbols data, filter out those that are members of private classes
+  var symbols = [];
+  var defines = [];
+  var typedefs = [];
+  var externs = [];
+  var base = [];
+  var augments = {};
+  var names = {};
+  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;
+  }).forEach(function(doc) {
+    var isExterns = (/[\\\/]externs$/).test(doc.meta.path);
+    if (isExterns && doc.longname.indexOf('olx.') === 0) {
+      if (doc.kind == 'typedef') {
+        typedefs.push({
+          name: doc.longname,
+          types: ['{}']
+        });
+      } else {
+        var typedef = typedefs[typedefs.length - 1];
+        var type = typedef.types[0];
+        typedef.types[0] = type
+            .replace(/\}$/, ', ' + doc.longname.split('#')[1] +
+                ': (' + getTypes(doc.type.names).join('|') + ')}')
+            .replace('{, ', '{');
+      }
+    } else if (doc.define) {
+      defines.push({
+        name: doc.longname,
+        description: doc.description,
+        path: path.join(doc.meta.path, doc.meta.filename),
+        default: doc.define.default
+      });
+    } else if (doc.kind == 'typedef' || doc.isEnum === true) {
+      typedefs.push({
+        name: doc.longname,
+        types: getTypes(doc.type.names)
+      });
+    } else {
+      var types;
+      var symbol = {
+        name: doc.longname,
+        kind: doc.kind,
+        description: doc.classdesc || doc.description,
+        stability: doc.api,
+        path: path.join(doc.meta.path, doc.meta.filename)
+      };
+      if (doc.augments) {
+        symbol.extends = doc.augments[0];
+      }
+      if (doc.virtual) {
+        symbol.virtual = true;
+      }
+      if (doc.type) {
+        symbol.types = getTypes(doc.type.names);
+      }
+      if (doc.params) {
+        var params = [];
+        doc.params.forEach(function(param) {
+          var paramInfo = {
+            name: param.name
+          };
+          params.push(paramInfo);
+          paramInfo.types = getTypes(param.type.names);
+          if (typeof param.variable == 'boolean') {
+            paramInfo.variable = param.variable;
+          }
+          if (typeof param.optional == 'boolean') {
+            paramInfo.optional = param.optional;
+          }
+          if (typeof param.nullable == 'boolean') {
+            paramInfo.nullable = param.nullable;
+          }
+        });
+        symbol.params = params;
+      }
+      if (doc.returns) {
+        symbol.returns = {
+          types: getTypes(doc.returns[0].type.names)
+        };
+        if (typeof doc.returns[0].nullable == 'boolean') {
+          symbol.returns.nullable = doc.returns[0].nullable;
+        }
+      }
+      if (doc.tags) {
+        doc.tags.every(function(tag) {
+          if (tag.title == 'template') {
+            symbol.template = tag.value;
+            return false;
+          }
+          return true;
+        });
+      }
+
+      var target = isExterns ? externs : (doc.api ? symbols : base);
+      target.push(symbol);
+      names[symbol.name] = true;
+
+      if (doc.api && symbol.extends) {
+        while (symbol.extends in classes && !classes[symbol.extends].api &&
+            classes[symbol.extends].augments) {
+          symbol.extends = classes[symbol.extends].augments[0];
+        }
+        if (symbol.extends) {
+          augments[symbol.extends] = true;
+        }
+      }
+    }
+  });
+
+  base = base.filter(function(symbol) {
+    var pass = symbol.name in augments || symbol.virtual;
+    if (pass) {
+      if (symbol.params) {
+        symbol.params.forEach(replaceUnknownTypes);
+      }
+      if (symbol.returns) {
+        symbol.returns.forEach(replaceUnknownTypes);
+      }
+    }
+    return pass;
+  });
+
+  process.stdout.write(
+      JSON.stringify({
+        symbols: symbols,
+        defines: defines,
+        typedefs: typedefs,
+        externs: externs,
+        base: base
+      }, null, 2));
+
+};

config/jsdoc/info/virtual-plugin.js

@@ -0,0 +1,16 @@
+/**
+ * Handle the interface and abstract annotations.
+ * @param {Object} dictionary The tag dictionary.
+ */
+exports.defineTags = function(dictionary) {
+
+  var classTag = dictionary.lookUp('class');
+  dictionary.defineTag('interface', {
+    mustHaveValue: false,
+    onTagged: function(doclet, tag) {
+      classTag.onTagged.apply(this, arguments);
+      doclet.virtual = true;
+    }
+  });
+
+};

config/readme.md

@@ -0,0 +1,3 @@
+# Configuration Files
+
+This directory includes configuration files for the build scripts in and documentation templates.

css/ol.css

@@ -191,6 +191,7 @@ button.ol-full-screen-true:after {
   text-align: right;
   bottom: .5em;
   right: .5em;
+  max-width: calc(100% - 1.3em);
 }
 
 .ol-attribution ul {
@@ -200,6 +201,7 @@ button.ol-full-screen-true:after {
   line-height: 1.375em;
   color: #000;
   text-shadow: 0 0 2px #fff;
+  max-width: calc(100% - 3.6em);
 }
 .ol-attribution li {
   display: inline;

doc/quickstart.hbs

@@ -13,14 +13,14 @@ Below you'll find a complete working example.  Create a new file, copy in the co
 <!doctype html>
 <html lang="en">
   <head>
-    <link rel="stylesheet" href="http://ol3js.org/en/{{ latest }}/css/ol.css" type="text/css">
+    <link rel="stylesheet" href="http://openlayers.org/en/{{ latest }}/css/ol.css" type="text/css">
     <style>
       .map {
         height: 400px;
         width: 100%;
       }
     </style>
-    <script src="http://ol3js.org/en/{{ latest }}/build/ol.js" type="text/javascript"></script>
+    <script src="http://openlayers.org/en/{{ latest }}/build/ol.js" type="text/javascript"></script>
     <title>OpenLayers 3 example</title>
   </head>
   <body>
@@ -55,10 +55,10 @@ To include a map a web page you will need 3 things:
 ### Include OpenLayers
 
 ```xml
-  <script src="http://ol3js.org/en/{{ latest }}/build/ol.js" type="text/javascript"></script>
+  <script src="http://openlayers.org/en/{{ latest }}/build/ol.js" type="text/javascript"></script>
 ```
 
-The first part is to include the JavaScript library. For the purpose of this tutorial, here we simply point to the ol3js.org website to get the whole library. In a production environment, we would build a custom version of the library including only the module needed for our application.
+The first part is to include the JavaScript library. For the purpose of this tutorial, here we simply point to the openlayers.org website to get the whole library. In a production environment, we would build a custom version of the library including only the module needed for our application.
 
 
 ### `<div>` to contain the map

examples/bind-input.js

@@ -1,17 +1,17 @@
-goog.require('ol.BrowserFeature');
 goog.require('ol.Map');
 goog.require('ol.View');
 goog.require('ol.control');
 goog.require('ol.dom.Input');
+goog.require('ol.has');
 goog.require('ol.layer.Tile');
 goog.require('ol.source.OSM');
 
 
 function checkWebGL(evt) {
   document.getElementById('no-webgl').style.display =
-      ol.BrowserFeature.HAS_WEBGL ? 'none' : '';
+      ol.has.WEBGL ? 'none' : '';
   document.getElementById('has-webgl').style.display =
-      ol.BrowserFeature.HAS_WEBGL && !evt.glContext ? '' : 'none';
+      ol.has.WEBGL && !evt.glContext ? '' : 'none';
   document.getElementById('webgl').style.display =
       evt.glContext ? '' : 'none';
 }

examples/brightness-contrast.js

@@ -1,6 +1,6 @@
-goog.require('ol.BrowserFeature');
 goog.require('ol.Map');
 goog.require('ol.View');
+goog.require('ol.has');
 goog.require('ol.layer.Tile');
 goog.require('ol.source.MapQuest');
 
@@ -14,7 +14,7 @@ function setResetContrastButtonHTML() {
   resetContrast.innerHTML = 'Contrast (' + layer.getContrast().toFixed(3) + ')';
 }
 
-if (!ol.BrowserFeature.HAS_WEBGL) {
+if (!ol.has.WEBGL) {
   var info = document.getElementById('no-webgl');
   /**
    * display error message

examples/drag-and-drop.html

@@ -32,7 +32,7 @@
 
         <div class="span4">
           <h4 id="title">Drag-and-Drop example</h4>
-          <p id="shortdesc">Example of using the drag-and-drop interaction. Drag and drop GPX, GeoJSON, IGC, KML, or TopoJSON files on to the map.</p>
+          <p id="shortdesc">Example of using the drag-and-drop interaction. Drag and drop GPX, GeoJSON, IGC, KML, or TopoJSON files on to the map. There is no projection transform support, so this will only work with data in EPSG:4326 and EPSG:3857.</p>
           <div id="docs">
             <p>See the <a href="drag-and-drop.js" target="_blank">drag-and-drop.js source</a> to see how this is done.</p>
           </div>

examples/getfeatureinfo-image.html

@@ -9,7 +9,7 @@
     <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>Get feature info example</title>
+    <title>GetFeatureInfo example (image layer)</title>
   </head>
   <body>
 
@@ -32,10 +32,10 @@
       <div class="row-fluid">
 
         <div class="span4">
-          <h4 id="title">GetFeatureInfo example</h4>
+          <h4 id="title">GetFeatureInfo example (image layer)</h4>
           <p id="shortdesc">This example shows how to trigger WMS GetFeatureInfo requests on click for a WMS image layer.</p>
           <div id="docs">
-            <p>See the <a href="getfeatureinfo.js" target="_blank">getfeatureinfo.js source</a> to see how this is done.</p>
+            <p>See the <a href="getfeatureinfo-image.js" target="_blank">getfeatureinfo-image.js source</a> to see how this is done.</p>
           </div>
           <div id="tags">getfeatureinfo</div>
         </div>
@@ -51,7 +51,7 @@
 
     <script src="jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
-    <script src="loader.js?id=getfeatureinfo" type="text/javascript"></script>
+    <script src="loader.js?id=getfeatureinfo-image" type="text/javascript"></script>
 
   </body>
 </html>

examples/getfeatureinfo-image.js

@@ -0,0 +1,38 @@
+goog.require('ol.Map');
+goog.require('ol.View');
+goog.require('ol.layer.Image');
+goog.require('ol.source.ImageWMS');
+
+
+var wmsSource = new ol.source.ImageWMS({
+  url: 'http://demo.opengeo.org/geoserver/wms',
+  params: {'LAYERS': 'ne:ne'},
+  serverType: 'geoserver'
+});
+
+var wmsLayer = new ol.layer.Image({
+  source: wmsSource
+});
+
+var view = new ol.View({
+  center: [0, 0],
+  zoom: 1
+});
+
+var map = new ol.Map({
+  layers: [wmsLayer],
+  target: 'map',
+  view: view
+});
+
+map.on('singleclick', function(evt) {
+  document.getElementById('info').innerHTML = '';
+  var viewResolution = /** @type {number} */ (view.getResolution());
+  var url = wmsSource.getGetFeatureInfoUrl(
+      evt.coordinate, viewResolution, 'EPSG:3857',
+      {'INFO_FORMAT': 'text/html'});
+  if (url) {
+    document.getElementById('info').innerHTML =
+        '<iframe seamless src="' + url + '"></iframe>';
+  }
+});

examples/getfeatureinfo-tile.html

@@ -0,0 +1,57 @@
+<!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="../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>WMS GetFeatureInfo example (tile layer)</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">WMS GetFeatureInfo example (tile layer)</h4>
+          <p id="shortdesc">This example shows how to trigger WMS GetFeatureInfo requests on click for a WMS tile layer.</p>
+          <div id="docs">
+            <p>See the <a href="getfeatureinfo-tile.js" target="_blank">getfeatureinfo-tile.js source</a> to see how this is done.</p>
+          </div>
+          <div id="tags">getfeatureinfo</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=getfeatureinfo-tile" type="text/javascript"></script>
+
+  </body>
+</html>

examples/getfeatureinfo-tile.js

@@ -6,7 +6,8 @@ goog.require('ol.source.TileWMS');
 
 var wmsSource = new ol.source.TileWMS({
   url: 'http://demo.opengeo.org/geoserver/wms',
-  params: {'LAYERS': 'ne:ne'}
+  params: {'LAYERS': 'ne:ne'},
+  serverType: 'geoserver'
 });
 
 var wmsLayer = new ol.layer.Tile({
@@ -18,8 +19,6 @@ var view = new ol.View({
   zoom: 1
 });
 
-var viewProjection = view.getProjection();
-
 var map = new ol.Map({
   layers: [wmsLayer],
   target: 'map',
@@ -30,7 +29,7 @@ map.on('singleclick', function(evt) {
   document.getElementById('info').innerHTML = '';
   var viewResolution = /** @type {number} */ (view.getResolution());
   var url = wmsSource.getGetFeatureInfoUrl(
-      evt.coordinate, viewResolution, viewProjection,
+      evt.coordinate, viewResolution, 'EPSG:3857',
       {'INFO_FORMAT': 'text/html'});
   if (url) {
     document.getElementById('info').innerHTML =

examples/hue-saturation.js

@@ -1,6 +1,6 @@
-goog.require('ol.BrowserFeature');
 goog.require('ol.Map');
 goog.require('ol.View');
+goog.require('ol.has');
 goog.require('ol.layer.Tile');
 goog.require('ol.proj');
 goog.require('ol.source.BingMaps');
@@ -15,7 +15,7 @@ function setResetSaturationButtonHTML() {
       layer.getSaturation().toFixed(2) + ')';
 }
 
-if (!ol.BrowserFeature.HAS_WEBGL) {
+if (!ol.has.WEBGL) {
   var info = document.getElementById('no-webgl');
   /**
    * display error message

examples/kml-earthquakes.js

@@ -39,6 +39,7 @@ var styleFunction = function(feature, resolution) {
 
 var vector = new ol.layer.Vector({
   source: new ol.source.KML({
+    extractStyles: false,
     projection: 'EPSG:3857',
     url: 'data/kml/2012_Earthquakes_Mag5.kml'
   }),

examples/layer-clipping-webgl.js

@@ -1,11 +1,11 @@
-goog.require('ol.BrowserFeature');
 goog.require('ol.Map');
 goog.require('ol.View');
 goog.require('ol.control');
+goog.require('ol.has');
 goog.require('ol.layer.Tile');
 goog.require('ol.source.OSM');
 
-if (!ol.BrowserFeature.HAS_WEBGL) {
+if (!ol.has.WEBGL) {
   var info = document.getElementById('no-webgl');
   /**
    * display error message

examples/mapguide-untiled.js

@@ -1,7 +1,7 @@
 goog.require('ol.Map');
 goog.require('ol.View');
 goog.require('ol.layer.Image');
-goog.require('ol.source.MapGuide');
+goog.require('ol.source.ImageMapGuide');
 
 var mdf = 'Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition';
 var agentUrl =
@@ -16,7 +16,7 @@ var map = new ol.Map({
   layers: [
     new ol.layer.Image({
       extent: bounds,
-      source: new ol.source.MapGuide({
+      source: new ol.source.ImageMapGuide({
         projection: 'EPSG:4326',
         url: agentUrl,
         useOverlay: false,

examples/readme.md

@@ -13,4 +13,4 @@ To enable this, examples have the following, not needed in application code:
 * html files load `example-behaviour.js` and some js files define the Map renderer option as `exampleNS.getRendererFromQueryString()`; application code would not need these
 * in addition, examples use Twitter Bootstrap and jQuery; this is of course not a requirement - you may use whichever presentation/helper libraries you wish
 
-See [Quick Start tutorial](http://ol3js.org/en/master/doc/quickstart.html) for a simple example of how application code would use the library.
+See [Quick Start tutorial](http://openlayers.org/en/master/doc/quickstart.html) for a simple example of how application code would use the library.

examples/scale-line.html

@@ -27,7 +27,9 @@
           <div id="map" class="map"></div>
           <select id="units">
             <option value="degrees">degrees</option>
-            <option value="imperial">imperial</option>
+            <option value="imperial">imperial inch</option>
+            <option value="us">us inch</option>
+            <option value="nautical">nautical mile</option>
             <option value="metric">metric</option>
           </select>
         </div>

examples/side-by-side.js

@@ -1,6 +1,6 @@
-goog.require('ol.BrowserFeature');
 goog.require('ol.Map');
 goog.require('ol.View');
+goog.require('ol.has');
 goog.require('ol.layer.Tile');
 goog.require('ol.source.MapQuest');
 
@@ -19,7 +19,7 @@ var domMap = new ol.Map({
   })
 });
 
-if (ol.BrowserFeature.HAS_WEBGL) {
+if (ol.has.WEBGL) {
   var webglMap = new ol.Map({
     renderer: 'webgl',
     target: 'webglMap'

examples/tile-vector.html

@@ -9,6 +9,12 @@
     <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>
+    <style>
+      #map {
+        max-width: 600px;
+        margin: 0 auto;
+      }
+    </style>
   </head>
   <body>
 
@@ -36,6 +42,16 @@
           <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 class="alert">
+            <strong>Warning</strong> Map is becoming unresponsive with too many layers.
+          </div>
+          <fieldset>
+            <legend>Layers</legend>
+            <label class="checkbox"><input type="checkbox" id="landuse"/> Landuse</label>
+            <label class="checkbox"><input type="checkbox" id="buildings"/> Buildings</label>
+            <label class="checkbox"><input type="checkbox" id="water" checked/> Water</label>
+            <label class="checkbox"><input type="checkbox" id="roads" checked/> Roads</label>
+          </fieldset>
           <div id="tags">tile-vector, openstreetmap</div>
         </div>
 

examples/tile-vector.js

@@ -11,9 +11,7 @@ goog.require('ol.tilegrid.XYZ');
 
 var waterLayer = new ol.layer.Vector({
   source: new ol.source.TileVector({
-    format: new ol.format.TopoJSON({
-      defaultProjection: 'EPSG:4326'
-    }),
+    format: new ol.format.TopoJSON(),
     projection: 'EPSG:3857',
     tileGrid: new ol.tilegrid.XYZ({
       maxZoom: 19
@@ -31,9 +29,7 @@ var waterLayer = new ol.layer.Vector({
 var roadStyleCache = {};
 var roadLayer = new ol.layer.Vector({
   source: new ol.source.TileVector({
-    format: new ol.format.TopoJSON({
-      defaultProjection: 'EPSG:4326'
-    }),
+    format: new ol.format.TopoJSON(),
     projection: 'EPSG:3857',
     tileGrid: new ol.tilegrid.XYZ({
       maxZoom: 19
@@ -73,13 +69,101 @@ var roadLayer = new ol.layer.Vector({
   }
 });
 
+var buildingStyle = [
+  new ol.style.Style({
+    fill: new ol.style.Fill({
+      color: '#666',
+      opacity: 0.4
+    }),
+    stroke: new ol.style.Stroke({
+      color: '#444',
+      width: 1
+    })
+  })
+];
+var buildingLayer = 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-buildings/{z}/{x}/{y}.topojson'
+  }),
+  visible: false,
+  style: function(f, resolution) {
+    return (resolution < 10) ? buildingStyle : [];
+  }
+});
+
+var landuseStyleCache = {};
+var landuseLayer = 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-land-usages/{z}/{x}/{y}.topojson'
+  }),
+  visible: false,
+  style: function(feature, resolution) {
+    var kind = feature.get('kind');
+    var styleKey = kind;
+    var styleArray = landuseStyleCache[styleKey];
+    if (!styleArray) {
+      var color, width;
+      color = {
+        'parking': '#ddd',
+        'industrial': '#aaa',
+        'urban area': '#aaa',
+        'park': '#76C759',
+        'school': '#DA10E7',
+        'garden': '#76C759',
+        'pitch': '#D58F8D',
+        'scrub': '#3E7D28',
+        'residential': '#4C9ED9'
+      }[kind];
+      width = kind == 'highway' ? 1.5 : 1;
+      styleArray = [new ol.style.Style({
+        stroke: new ol.style.Stroke({
+          color: color,
+          width: width
+        }),
+        fill: new ol.style.Fill({
+          color: color,
+          opacity: 0.5
+        })
+      })];
+      landuseStyleCache[styleKey] = styleArray;
+    }
+    return styleArray;
+  }
+});
+
 var map = new ol.Map({
-  layers: [waterLayer, roadLayer],
+  layers: [landuseLayer, buildingLayer, waterLayer, roadLayer],
   renderer: 'canvas',
   target: document.getElementById('map'),
   view: new ol.View({
     center: ol.proj.transform([-74.0064, 40.7142], 'EPSG:4326', 'EPSG:3857'),
     maxZoom: 19,
-    zoom: 14
+    zoom: 15
   })
 });
+
+$('input[type=checkbox]').on('change', function() {
+  var layer = {
+    landuse: landuseLayer,
+    buildings: buildingLayer,
+    water: waterLayer,
+    roads: roadLayer
+  }[$(this).attr('id')];
+  layer.setVisible(!layer.getVisible());
+});

examples/tissot.js

@@ -1,12 +1,12 @@
 goog.require('ol.Feature');
 goog.require('ol.Map');
+goog.require('ol.Sphere');
 goog.require('ol.View');
 goog.require('ol.geom.Polygon');
 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();
 
@@ -33,11 +33,12 @@ var map = new ol.Map({
   })
 });
 
+var wgs84Sphere = new ol.Sphere(6378137);
 
 var radius = 800000;
 for (var x = -180; x < 180; x += 30) {
   for (var y = -90; y < 90; y += 30) {
-    var circle = ol.geom.Polygon.circular(ol.sphere.WGS84, [x, y], radius, 64);
+    var circle = ol.geom.Polygon.circular(wgs84Sphere, [x, y], radius, 64);
     vectorSource.addFeature(new ol.Feature(circle));
   }
 }

examples/wmts-hidpi.js

@@ -1,6 +1,6 @@
-goog.require('ol.BrowserFeature');
 goog.require('ol.Map');
 goog.require('ol.View');
+goog.require('ol.has');
 goog.require('ol.layer.Tile');
 goog.require('ol.source.WMTS');
 goog.require('ol.tilegrid.WMTS');
@@ -20,7 +20,7 @@ var urls = [
 // HiDPI support:
 // * Use 'bmaphidpi' layer (pixel ratio 2) for device pixel ratio > 1
 // * Use 'geolandbasemap' layer (pixel ratio 1) for device pixel ratio == 1
-var hiDPI = ol.BrowserFeature.DEVICE_PIXEL_RATIO > 1;
+var hiDPI = ol.has.DEVICE_PIXEL_RATIO > 1;
 
 var source = new ol.source.WMTS({
   projection: 'EPSG:3857',

examples/xyz-retina.js

@@ -8,7 +8,8 @@ goog.require('ol.source.XYZ');
 
 
 var attribution = new ol.Attribution({
-  html: 'Tiles rendered with <a href="http://www.maptiler.com/"> &copy; USGS'
+  html: 'Tiles &copy; USGS, rendered with ' +
+      '<a href="http://www.maptiler.com/">MapTiler</a>'
 });
 
 var mapMinZoom = 1;
@@ -22,11 +23,11 @@ var map = new ol.Map({
       source: new ol.source.OSM()
     }),
     new ol.layer.Tile({
+      extent: ol.proj.transformExtent(mapExtent, 'EPSG:4326', 'EPSG:3857'),
       source: new ol.source.XYZ({
+        attributions: [attribution],
         url: 'http://tileserver.maptiler.com/grandcanyon@2x/{z}/{x}/{y}.png',
         tilePixelRatio: 2, // THIS IS IMPORTANT
-        maxExtent: ol.proj.transformExtent(
-            mapExtent, 'EPSG:4326', 'EPSG:3857'),
         minZoom: mapMinZoom,
         maxZoom: mapMaxZoom
       })

externs/geojson.js

@@ -52,6 +52,13 @@ GeoJSONCRS.prototype.properties;
 var GeoJSONCRSCode = function() {};
 
 
+
+/**
+ * @constructor
+ */
+var GeoJSONCRSName = function() {};
+
+
 /**
  * @type {string}
  * TODO: remove this when http://jira.codehaus.org/browse/GEOS-5996 is fixed
@@ -60,13 +67,6 @@ var GeoJSONCRSCode = function() {};
 GeoJSONCRSName.prototype.code;
 
 
-
-/**
- * @constructor
- */
-var GeoJSONCRSName = function() {};
-
-
 /**
  * @type {string}
  */

package.json

@@ -3,7 +3,8 @@
   "version": "3.0.0-beta",
   "description": "Mapping library",
   "scripts": {
-    "postinstall": "node tasks/parse-examples.js",
+    "install": "node tasks/parse-examples.js",
+    "postinstall": "node ./node_modules/closure-util/install.js",
     "start": "node tasks/serve.js",
     "test": "node tasks/test.js"
   },

src/ol/attribution.js

@@ -23,7 +23,7 @@ goog.require('ol.TileRange');
  * @constructor
  * @param {olx.AttributionOptions} options Attribution options.
  * @struct
- * @api
+ * @api stable
  */
 ol.Attribution = function(options) {
 
@@ -45,6 +45,7 @@ ol.Attribution = function(options) {
 
 /**
  * @return {string} HTML.
+ * @api stable
  */
 ol.Attribution.prototype.getHTML = function() {
   return this.html_;

src/ol/binary.js

@@ -5,7 +5,7 @@ goog.provide('ol.binary.IReader');
 
 goog.require('goog.asserts');
 goog.require('goog.userAgent');
-goog.require('ol.BrowserFeature');
+goog.require('ol.has');
 
 
 
@@ -29,7 +29,7 @@ ol.binary.Buffer = function(data) {
  */
 ol.binary.Buffer.prototype.getReader = function() {
   var data = this.data_;
-  if (ol.BrowserFeature.HAS_ARRAY_BUFFER) {
+  if (ol.has.ARRAY_BUFFER) {
     var arrayBuffer;
     if (data instanceof ArrayBuffer) {
       arrayBuffer = data;

src/ol/browserfeature.jsdoc

@@ -1,3 +0,0 @@
-/**
- * @namespace ol.BrowserFeature
- */

src/ol/centerconstraint.js

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

src/ol/collection.js

@@ -33,6 +33,10 @@ ol.CollectionEventType = {
 
 
 /**
+ * @classdesc
+ * Events emitted by {@link ol.Collection} instances are instances of this
+ * type.
+ *
  * @constructor
  * @extends {goog.events.Event}
  * @implements {oli.CollectionEvent}
@@ -188,8 +192,9 @@ ol.Collection.prototype.insertAt = function(index, elem) {
 
 
 /**
- * Remove the last element of the collection.
- * @return {T} Element.
+ * Remove the last element of the collection and return it.
+ * Return `undefined` if the collection is empty.
+ * @return {T|undefined} Element.
  * @api stable
  */
 ol.Collection.prototype.pop = function() {
@@ -229,9 +234,10 @@ ol.Collection.prototype.remove = function(elem) {
 
 
 /**
- * Remove the element at the provided index.
+ * Remove the element at the provided index and return it.
+ * Return `undefined` if the collection does not contain this index.
  * @param {number} index Index.
- * @return {T} Value.
+ * @return {T|undefined} Value.
  * @api stable
  */
 ol.Collection.prototype.removeAt = function(index) {

src/ol/color/color.js

@@ -110,7 +110,7 @@ ol.color.asArray = function(color) {
 
 /**
  * @param {ol.Color|string} color Color.
- * @return {string} String.
+ * @return {string} Rgba string.
  * @api
  */
 ol.color.asString = function(color) {
@@ -242,7 +242,7 @@ ol.color.fromStringInternal_ = function(s) {
     color = [r, g, b, 1];
     return ol.color.normalize(color, color);
   } else {
-    throw new Error(s + ' is not a valid color');
+    goog.asserts.fail(s + ' is not a valid color');
   }
 
 };

src/ol/color/color.jsdoc

@@ -1,3 +1,8 @@
 /**
+ * Colors can be defined as a {@link ol.Color} array, or as strings in
+ * `rgb(r,g,b)` or `rgba(r,g,b,a)` format, or in hex `#rrggbb` or `#rgb` format.
+ * Color names, like 'red', 'blue' or 'green', may also be used with the
+ * Canvas renderer.
+ *
  * @namespace ol.color
  */

src/ol/control/attributioncontrol.js

@@ -26,7 +26,7 @@ goog.require('ol.pointer.PointerEventHandler');
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.AttributionOptions=} opt_options Attribution options.
- * @api
+ * @api stable
  */
 ol.control.Attribution = function(opt_options) {
 
@@ -362,7 +362,7 @@ ol.control.Attribution.prototype.handleToggle_ = function() {
 
 /**
  * @return {boolean} True if the widget is collapsible.
- * @api
+ * @api stable
  */
 ol.control.Attribution.prototype.getCollapsible = function() {
   return this.collapsible_;
@@ -371,7 +371,7 @@ ol.control.Attribution.prototype.getCollapsible = function() {
 
 /**
  * @param {boolean} collapsible True if the widget is collapsible.
- * @api
+ * @api stable
  */
 ol.control.Attribution.prototype.setCollapsible = function(collapsible) {
   if (this.collapsible_ === collapsible) {
@@ -387,7 +387,7 @@ ol.control.Attribution.prototype.setCollapsible = function(collapsible) {
 
 /**
  * @param {boolean} collapsed True if the widget is collapsed.
- * @api
+ * @api stable
  */
 ol.control.Attribution.prototype.setCollapsed = function(collapsed) {
   if (!this.collapsible_ || this.collapsed_ === collapsed) {
@@ -399,7 +399,7 @@ ol.control.Attribution.prototype.setCollapsed = function(collapsed) {
 
 /**
  * @return {boolean} True if the widget is collapsed.
- * @api
+ * @api stable
  */
 ol.control.Attribution.prototype.getCollapsed = function() {
   return this.collapsed_;

src/ol/control/control.js

@@ -82,7 +82,7 @@ ol.control.Control.prototype.disposeInternal = function() {
 /**
  * Get the map associated with this control.
  * @return {ol.Map} Map.
- * @api
+ * @api stable
  */
 ol.control.Control.prototype.getMap = function() {
   return this.map_;

src/ol/control/controldefaults.js

@@ -16,7 +16,7 @@ goog.require('ol.control.Zoom');
  *
  * @param {olx.control.DefaultsOptions=} opt_options Defaults options.
  * @return {ol.Collection.<ol.control.Control>} Controls.
- * @api
+ * @api stable
  */
 ol.control.defaults = function(opt_options) {