Merge pull request #2075 from ahocevar/api-docs-improved

More API doc improvements

apidoc/index.md

@@ -1,20 +1,41 @@
-Finding your way around
------------------------
-See the class list to the right and especially take a look at {@link ol.Map} and {@link ol.layer.Layer} because those are the central objects.
-
-In general every use of OpenLayers starts by initializing a map, then adding the required layers. Controls and interactions can be added to change the behavior of the map.
-
-Projections
------------
-A {@link ol.proj.Projection} defines which point on earth is represented by a pair of coordinates.
-Coordinates within OpenLayers can be used in various projections where some common projections are always supported,
-others can be used via [Proj4js](http://trac.osgeo.org/proj4js/).
-
-Maps and Layers
----------------
-A map in OpenLayers is essentially a staple of layers that is viewed from the top. Layers are responsible for retrieving data and displaying it.
-
-Contributing
-------------
-See [CONTRIBUTING.md](https://github.com/openlayers/ol3/blob/master/CONTRIBUTING.md) for instructions
-on building and testing OpenLayers. The file does also describe how to commit your changes to OpenLayers.
+<table><tr>
+<th width="33.3%">Map</th><th width="33.3%">View</th><th width="33.3%">Layers</th>
+</tr><tr>
+<td><p>A [map](ol.Map.html) is made of [layers](ol.layer.html), a [view](ol.View.html) to visualize them, [interactions](ol.interaction.html) to modify map content and [controls](ol.control.html) with UI components.</p>
+[Overview](ol.Map.html)<br>
+[Creation](ol.Map.html#Map)<br>
+[Events](ol.MapBrowserEvent.html)</td>
+<td><p>The view manages the visual parameters of the map view, like resolution or rotation.</p>
+[ol.View2D](ol.View2D.html) with center, projection, resolution and rotation</td>
+<td><p>Layers are lightweight containers that get their data from [sources](ol.source.html).</p>
+[ol.layer.Tile](ol.layer.Tile.html)<br>
+[ol.layer.Image](ol.layer.Image)<br>
+[ol.layer.Vector](ol.layer.Vector)</td>
+</tr><tr>
+<th>Controls</th><th>Interactions</th><th>Sources and formats</th>
+</tr><tr>
+<td>[Map default controls](ol.control.html#defaults)<br>
+[All controls](ol.control.html)
+</td>
+<td>
+[Map default interactions](ol.interaction.html#defaults)<br>
+Interactions for [vector features](ol.Feature.html)
+<ul><li>[ol.interaction.Select](ol.interaction.Select.html)</li>
+<li>[ol.interaction.Draw](ol.interaction.Draw.html)</li>
+<li>[ol.interaction.Modify](ol.interaction.Modify.html)</li></ul>
+[All interactions](ol.interaction.html)</td>
+<td>[Tile sources](ol.source.Tile.html) for [ol.layer.Tile](ol.layer.Tile.html)
+<br>[Image sources](ol.source.Image.html) for [ol.layer.Image](ol.layer.Image)
+<br>[Vector sources](ol.source.Vector.html) for [ol.layer.Vector](ol.layer.Vector)
+<br>[Formats](ol.format.Feature.html) for reading/writing vector data
+<br>[ol.format.WMSCapabilities](ol.format.WMSCapabilities.html)</td></tr>
+<tr><th>Projections</th><th>2-way bindings</th><th>Other components</th></tr>
+<tr><td><p>All coordinates and extents need to be provided in map projection (default: [EPSG:3857](ol.proj.EPSG3857.html)). To transform, use [ol.proj.transform()](ol.proj.html#transform).</p>
+[ol.proj](ol.proj.html)</td>
+<td><p>[Objects](ol.Object.html) can be kept in sync using the [bindTo()](ol.Object.html#bindTo) method.</p>
+<p>A [DOM Input](ol.dom.Input.html) class is available to bind Object properties to HTML Input elements.</p></td>
+<td>[ol.DeviceOrientation](ol.DeviceOrientation.html)<br>
+[ol.Geolocation](ol.Geolocation.html)<br>
+[ol.Overlay](ol.Overlay.html)<br>
+[ol.FeatureOverlay](ol.FeatureOverlay.html)<br></td>
+</tr></table>

apidoc/plugins/events.js

@@ -29,15 +29,11 @@ exports.handlers = {
             event = doclet.fires[j].replace('event:', '');
             if (events[event]) {
               fires.push.apply(fires, events[event]);            
+            } else {
+              fires.push(doclet.fires[j]);
             }
           }
           doclet.fires = fires;
-        } else {
-          eventClass = classes[doclet.longname.split('#')[0]];
-          if (!eventClass.fires) {
-            eventClass.fires = [];
-          }
-          eventClass.fires.push.apply(eventClass.fires, doclet.fires);
         }
       }
     }

apidoc/template/static/styles/jaguar.css

@@ -160,17 +160,6 @@ li {
 .main dd, .main .props {
   font-size: 13px;
 }
-.main h4.name span.type-signature {
-  display: inline-block;
-  border-radius: 3px;
-  background-color: gray;
-  color: #fff;
-  font-size: 0.7em;
-  padding: 2px 4px;
-}
-.main h4.name span.type-signature.type a {
-  color: #2f61b1;
-}
 .main h4.name span.type {
   margin-left: 10px;
 }
@@ -180,7 +169,7 @@ li {
   color: #c1c1c1;
   margin-left: 7px;
 }
-.main h4.name span.returnType {
+.main h4.name span.returnType, .main h4.name span.type {
   margin-left: 3px;
   background-color: transparent!important;
   color: gray!important;
@@ -194,25 +183,8 @@ li {
   font-size: 0.8em;
   padding: 2px 4px;
 }
-.main span.number {
-  background-color: #ccc !important;
-  color: #2fa2b1 !important;
-}
-.main span.string {
-  background-color: #ccc !important;
-  color: #2fa2b1 !important;
-}
-.main span.object {
-  background-color: #ccc !important;
-  color: #2fa2b1 !important;
-}
-.main span.array {
-  background-color: #ccc !important;
-  color: #2fa2b1 !important;
-}
-.main span.boolean {
-  background-color: #ccc !important;
-  color: #2fa2b1 !important;
+span.type-signature.static {
+  margin-right: 3px;
 }
 .main .subsection-title {
   font-size: 15px;
@@ -325,7 +297,7 @@ li {
 .main table .description p {
   margin: 0;
 }
-.main table .optional {
+.main table .optional, .main table .repeatable {
   float: left;
   border-radius: 3px;
   background-color: #ddd!important;
@@ -388,3 +360,12 @@ footer {
   background-color: #468847 !important;
   color: #dff0d8;
 }
+.main .readme table p {
+  margin-top: 0;
+}
+.main .readme table p, .main .readme table td {
+  font-size: 14px;
+}
+.main .readme table ul li {
+  margin-bottom: 0;
+}

apidoc/template/tmpl/members.tmpl

@@ -5,7 +5,7 @@ var typeSignature = '';
 
 if (data.type && data.type.names) {
     data.type.names.forEach(function (name) {
-        typeSignature += '<span class="type-signature type ' + name.toLowerCase() + '">' + self.linkto(name, self.htmlsafe(name)) + '</span> ';
+        typeSignature += '<span class="type-signature type ' + name.toLowerCase() + '">{' + self.linkto(name, self.htmlsafe(name)) + '}</span> ';
     });
 }
 ?>

apidoc/template/tmpl/method.tmpl

@@ -57,18 +57,27 @@ var self = this;
     <h5>Fires:</h5>
     <ul><?js fires.forEach(function(f) {
             var parts = f.split(/#?event:/);
+            var type = parts.pop();
+            var eventClassName = parts[0];
+            parts = type.split(' ');
+            type = parts.shift();
+            var description = parts.length ? parts.join(' ') : '';
+            var eventDoclet = self.find({longname: f})[0];
+            if (eventDoclet && !description && eventDoclet.description) {
+              description = eventDoclet.description.replace(/<[^>]*>/g, '');
+            }
         ?>
-        <li><?js var eventDoclet = self.find({longname: f})[0]; ?>
-            <code><?js= self.linkto(f, parts[1]) ?></code>
-            <?js if (parts[0]) {
-              var eventClass = self.find({longname: parts[0]})[0];
+        <li>
+            <code><?js= self.linkto(f, type) ?></code>
+            <?js if (eventClassName) {
+              var eventClass = self.find({longname: eventClassName})[0];
               if (eventClass) { ?>
                 (<?js= self.linkto(eventClass.longname) ?>)
               <?js } ?>
             <?js } ?>
-            <?js if (eventDoclet && eventDoclet.description) { ?> -
-            <?js= (eventDoclet ? self.partial('stability.tmpl', eventDoclet) : '') ?>
-            <?js= eventDoclet.description.replace(/<[^>]*>/g, '') ?>
+            <?js if (description) { ?> -
+            <?js= self.partial('stability.tmpl', eventDoclet || (data.stability ? data : {stability: 'experimental'})) ?>
+            <?js= description ?>
             <?js } ?>
         </li>
     <?js }); ?></ul>

apidoc/template/tmpl/params.tmpl

@@ -24,9 +24,15 @@
     var colspan = 2;
     params.forEach(function(param) {
         if (!param) { return; }
+        if (param.type && param.type.names && param.type.names.indexOf('undefined') !== -1) {
+            param.optional = true;
+        }
+        if (param.name.indexOf('var_') == 0) {
+            params.hasAttributes = true;
+            param.variable = true;
+        }
         
         if (param.optional || param.nullable) {
-            ++colspan;
             params.hasAttributes = true;
         }
         
@@ -50,10 +56,6 @@
 		
 		<th>Type</th>
 		
-		<?js if (params.hasAttributes) {?>
-		<th>Argument</th>
-		<?js } ?>
-		
 		<?js if (params.hasDefault) {?>
 		<th>Default</th>
 		<?js } ?>
@@ -81,18 +83,6 @@
             <?js } ?>
             </td>
             
-            <?js if (params.hasAttributes) {?>
-                <td class="attributes">
-                <?js if (param.optional) { ?>
-                    &lt;optional><br>
-                <?js } ?>
-                    
-                <?js if (param.nullable) { ?>
-                    &lt;nullable><br>
-                <?js } ?>
-                </td>
-            <?js } ?>
-            
             <?js if (params.hasDefault) {?>
                 <td class="default">
                 <?js if (typeof param.defaultvalue !== 'undefined') { ?>

examples/geolocation-orientation.js

@@ -36,7 +36,8 @@ map.addOverlay(marker);
 // LineString to store the different geolocation positions. This LineString
 // is time aware.
 // The Z dimension is actually used to store the rotation (heading).
-var positions = new ol.geom.LineString([], 'XYZM');
+var positions = new ol.geom.LineString([],
+    /** @type {ol.geom.GeometryLayout} */ ('XYZM'));
 
 // Geolocation Control
 var geolocation = new ol.Geolocation(/** @type {olx.GeolocationOptions} */ ({

externs/olx.js

@@ -683,7 +683,7 @@ olx.control.ControlOptions.prototype.target;
  *     logo: (boolean|undefined),
  *     logoOptions: (olx.control.LogoOptions|undefined),
  *     zoom: (boolean|undefined),
- *     rotateOptions: (olx.control.RotateOptions|undefined)}}
+ *     rotateOptions: (olx.control.RotateOptions|undefined),
  *     zoomOptions: (olx.control.ZoomOptions|undefined)}}
  * @todo api
  */
@@ -890,7 +890,7 @@ olx.control.ScaleLineOptions.prototype.units;
  *     tipLabel: (string|undefined),
  *     target: (Element|undefined),
  *     autoHide: (boolean|undefined)}}
- * @todo stability experimental
+ * @todo api
  */
 olx.control.RotateOptions;
 
@@ -3909,8 +3909,8 @@ olx.source.TileWMSOptions.prototype.projection;
 
 
 /**
- * The type of the remote WMS server: `mapserver`, `geoserver` or `qgis`. Only
- * needed if `hidpi` is `true`. Default is `undefined`.
+ * The type of the remote WMS server. Currently only used when `hidpi` is
+ * `true`. Default is `undefined`.
  * @type {ol.source.wms.ServerType|string|undefined}
  */
 olx.source.TileWMSOptions.prototype.serverType;

simple.json

@@ -0,0 +1,25 @@
+{
+  "exports": [],
+  "src": ["src/**/*.js", "examples/simple.js"],
+  "compile": {
+    "js": ["externs/olx.js"],
+    "externs": [
+      "externs/example.js",
+      "externs/bingmaps.js",
+      "externs/geojson.js",
+      "externs/oli.js",
+      "externs/proj4js.js",
+      "externs/tilejson.js",
+      "externs/topojson.js",
+      "externs/vbarray.js"
+    ],
+    "define": [
+      "goog.dom.ASSUME_STANDARDS_MODE=true",
+      "goog.DEBUG=false"
+    ],
+    "compilation_level": "ADVANCED_OPTIMIZATIONS",
+    "output_wrapper": "(function(){%output%})();",
+    "use_types_for_optimization": true,
+    "manage_closure_dependencies": true
+  }
+}

src/ol/control/controldefaults.js

@@ -8,6 +8,12 @@ goog.require('ol.control.Zoom');
 
 
 /**
+ * Set of default controls. Unless configured otherwise, this returns a
+ * collection containing an instance of each of the following controls:
+ * * {@link ol.control.Zoom}
+ * * {@link ol.control.Rotate}
+ * * {@link ol.control.Attribution}
+ * * {@link ol.control.Logo}
  * @param {olx.control.DefaultsOptions=} opt_options Defaults options.
  * @return {ol.Collection} Controls.
  * @todo api

src/ol/deviceorientation.js

@@ -68,6 +68,7 @@ ol.DeviceOrientationProperty = {
  *
  * @constructor
  * @extends {ol.Object}
+ * @fires change Triggered when the device orientation changes.
  * @param {olx.DeviceOrientationOptions=} opt_options Options.
  * @todo api
  */

src/ol/feature.js

@@ -18,6 +18,7 @@ goog.require('ol.style.Style');
 /**
  * @constructor
  * @extends {ol.Object}
+ * @fires change Triggered when the geometry or style of the feature changes.
  * @param {ol.geom.Geometry|Object.<string, *>=} opt_geometryOrValues
  *     Values or geometry.
  * @todo api

src/ol/geolocation.js

@@ -51,6 +51,7 @@ ol.GeolocationProperty = {
  *
  * @constructor
  * @extends {ol.Object}
+ * @fires change Triggered when the position changes.
  * @param {olx.GeolocationOptions=} opt_options Options.
  * @todo api
  */

src/ol/geom/circle.js

@@ -13,7 +13,7 @@ goog.require('ol.geom.flat.deflate');
  * @extends {ol.geom.SimpleGeometry}
  * @param {ol.geom.RawPoint} center Center.
  * @param {number=} opt_radius Radius.
- * @param {ol.geom.GeometryLayout|string=} opt_layout Layout.
+ * @param {ol.geom.GeometryLayout=} opt_layout Layout.
  * @todo api
  */
 ol.geom.Circle = function(center, opt_radius, opt_layout) {

src/ol/geom/geometry.js

@@ -46,6 +46,7 @@ ol.geom.GeometryLayout = {
 /**
  * @constructor
  * @extends {ol.Observable}
+ * @fires change Triggered when the geometry changes.
  * @todo api
  */
 ol.geom.Geometry = function() {

src/ol/geom/linearring.js

@@ -15,7 +15,7 @@ goog.require('ol.geom.flat.simplify');
  * @constructor
  * @extends {ol.geom.SimpleGeometry}
  * @param {ol.geom.RawLinearRing} coordinates Coordinates.
- * @param {ol.geom.GeometryLayout|string=} opt_layout Layout.
+ * @param {ol.geom.GeometryLayout=} opt_layout Layout.
  * @todo api
  */
 ol.geom.LinearRing = function(coordinates, opt_layout) {

src/ol/geom/linestring.js

@@ -19,7 +19,7 @@ goog.require('ol.geom.flat.simplify');
  * @constructor
  * @extends {ol.geom.SimpleGeometry}
  * @param {ol.geom.RawLineString} coordinates Coordinates.
- * @param {ol.geom.GeometryLayout|string=} opt_layout Layout.
+ * @param {ol.geom.GeometryLayout=} opt_layout Layout.
  * @todo api
  */
 ol.geom.LineString = function(coordinates, opt_layout) {

src/ol/geom/multilinestring.js

@@ -19,7 +19,7 @@ goog.require('ol.geom.flat.simplify');
  * @constructor
  * @extends {ol.geom.SimpleGeometry}
  * @param {ol.geom.RawMultiLineString} coordinates Coordinates.
- * @param {ol.geom.GeometryLayout|string=} opt_layout Layout.
+ * @param {ol.geom.GeometryLayout=} opt_layout Layout.
  * @todo api
  */
 ol.geom.MultiLineString = function(coordinates, opt_layout) {

src/ol/geom/multipoint.js

@@ -17,7 +17,7 @@ goog.require('ol.math');
  * @constructor
  * @extends {ol.geom.SimpleGeometry}
  * @param {ol.geom.RawMultiPoint} coordinates Coordinates.
- * @param {ol.geom.GeometryLayout|string=} opt_layout Layout.
+ * @param {ol.geom.GeometryLayout=} opt_layout Layout.
  * @todo api
  */
 ol.geom.MultiPoint = function(coordinates, opt_layout) {

src/ol/geom/multipolygon.js

@@ -24,7 +24,7 @@ goog.require('ol.geom.flat.simplify');
  * @constructor
  * @extends {ol.geom.SimpleGeometry}
  * @param {ol.geom.RawMultiPolygon} coordinates Coordinates.
- * @param {ol.geom.GeometryLayout|string=} opt_layout Layout.
+ * @param {ol.geom.GeometryLayout=} opt_layout Layout.
  * @todo api
  */
 ol.geom.MultiPolygon = function(coordinates, opt_layout) {

src/ol/geom/point.js

@@ -13,7 +13,7 @@ goog.require('ol.math');
  * @constructor
  * @extends {ol.geom.SimpleGeometry}
  * @param {ol.geom.RawPoint} coordinates Coordinates.
- * @param {ol.geom.GeometryLayout|string=} opt_layout Layout.
+ * @param {ol.geom.GeometryLayout=} opt_layout Layout.
  * @todo api
  */
 ol.geom.Point = function(coordinates, opt_layout) {

src/ol/geom/polygon.js

@@ -23,7 +23,7 @@ goog.require('ol.geom.flat.simplify');
  * @constructor
  * @extends {ol.geom.SimpleGeometry}
  * @param {ol.geom.RawPolygon} coordinates Coordinates.
- * @param {ol.geom.GeometryLayout|string=} opt_layout Layout.
+ * @param {ol.geom.GeometryLayout=} opt_layout Layout.
  * @todo api
  */
 ol.geom.Polygon = function(coordinates, opt_layout) {

src/ol/interaction/dragboxinteraction.js

@@ -35,7 +35,7 @@ ol.DragBoxEventType = {
   BOXSTART: 'boxstart',
   /**
    * Triggered upon drag box end.
-   * @event ol.DragBoxEvent#boxstart
+   * @event ol.DragBoxEvent#boxend
    * @todo api
    */
   BOXEND: 'boxend'

src/ol/interaction/interactiondefaults.js

@@ -21,7 +21,16 @@ goog.require('ol.interaction.PinchZoom');
  * different order for interactions, you will need to create your own
  * {@link ol.interaction.Interaction} instances and insert them into a
  * {@link ol.Collection} in the order you want before creating your
- * {@link ol.Map} instance.
+ * {@link ol.Map} instance. The default set of interactions, in sequence, is:
+ * * {@link ol.interaction.DragRotate}
+ * * {@link ol.interaction.DoubleClickZoom}
+ * * {@link ol.interaction.DragPan}
+ * * {@link ol.interaction.PinchRotate}
+ * * {@link ol.interaction.PinchZoom}
+ * * {@link ol.interaction.KeyboardPan}
+ * * {@link ol.interaction.KeyboardZoom}
+ * * {@link ol.interaction.MouseWheelZoom}
+ * * {@link ol.interaction.DragZoom}
  * @param {olx.interaction.DefaultsOptions=} opt_options Defaults options.
  * @return {ol.Collection} A collection of interactions to be used with
  * the ol.Map constructor's interactions option.

src/ol/layer/layer.js

@@ -13,6 +13,7 @@ goog.require('ol.source.Source');
  * @constructor
  * @extends {ol.layer.Base}
  * @fires ol.render.Event
+ * @fires change Triggered when the state of the source changes.
  * @param {olx.layer.LayerOptions} options Layer options.
  * @todo api
  */

src/ol/layer/layergroup.js

@@ -27,6 +27,8 @@ ol.layer.GroupProperty = {
 /**
  * @constructor
  * @extends {ol.layer.Base}
+ * @fires change Triggered when the state of the source of any of the layers of
+ *     this group changes
  * @param {olx.layer.GroupOptions=} opt_options Layer options.
  * @todo api
  */

src/ol/map.js

@@ -158,7 +158,8 @@ ol.MapProperty = {
  * @param {olx.MapOptions} options Map options.
  * @fires ol.MapBrowserEvent
  * @fires ol.MapEvent
- * @fires ol.render.Event
+ * @fires ol.render.Event#postcompose
+ * @fires ol.render.Event#precompose
  * @todo api
  */
 ol.Map = function(options) {

src/ol/observable.js

@@ -31,8 +31,7 @@ goog.inherits(ol.Observable, goog.events.EventTarget);
 
 
 /**
- * Dispatches a `change` event. Register a listener for this event to get
- * notified of changes.
+ * Dispatches a `change` event.
  * @fires change
  * @todo api
  */

src/ol/source/source.js

@@ -35,6 +35,7 @@ ol.source.SourceOptions;
 /**
  * @constructor
  * @extends {ol.Observable}
+ * @fires change Triggered when the state of the source changes.
  * @param {ol.source.SourceOptions} options Source options.
  */
 ol.source.Source = function(options) {

src/ol/source/wmssource.js

@@ -3,7 +3,11 @@ goog.provide('ol.source.wms.ServerType');
 
 
 /**
+ * Available server types: `'carmentaserver'`, `'geoserver'`, `'mapserver'`,
+ *     `'qgis'`. These are servers that have vendor parameters beyond the WMS
+ *     specification that OpenLayers can make use of.
  * @enum {string}
+ * @todo api
  */
 ol.source.wms.ServerType = {
   CARMENTA_SERVER: 'carmentaserver',

src/ol/source/wmssource.jsdoc

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