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

More API doc improvements

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
+ */