Greatly simplify and document the usage of JSDoc

This commit simplifies the exports.js plugin so it only relies
on the stability notes to generate the documentation, which
completely decouples it from the exportable API.

As a rule of thumb, whenever something has an 'api' annotation,
it should also have a 'stability' annotation. A more verbose
documentation of ol3 specific annotation usage is available in
the new 'apidoc/readme.md' file.

This commit also modifies all source files to implement these
usage suggestions.

src/ol/geom/geometry.js

@@ -8,6 +8,7 @@ goog.require('ol.Observable');
 
 /**
  * @enum {string}
+ * @todo stability experimental
  */
 ol.geom.GeometryType = {
   POINT: 'Point',
@@ -24,6 +25,7 @@ ol.geom.GeometryType = {
 
 /**
  * @enum {string}
+ * @todo stability experimental
  */
 ol.geom.GeometryLayout = {
   XY: 'XY',
@@ -79,6 +81,7 @@ goog.inherits(ol.geom.Geometry, ol.Observable);
 
 
 /**
+ * @function
  * @return {ol.geom.Geometry} Clone.
  * @todo stability experimental
  */
@@ -113,7 +116,6 @@ ol.geom.Geometry.prototype.getClosestPoint = function(point, opt_closestPoint) {
 /**
  * @param {ol.Coordinate} coordinate Coordinate.
  * @return {boolean} Contains coordinate.
- * @todo stability experimental
  */
 ol.geom.Geometry.prototype.containsCoordinate = function(coordinate) {
   return this.containsXY(coordinate[0], coordinate[1]);
@@ -129,6 +131,7 @@ ol.geom.Geometry.prototype.containsXY = goog.functions.FALSE;
 
 
 /**
+ * @function
  * @param {ol.Extent=} opt_extent Extent.
  * @return {ol.Extent} extent Extent.
  * @todo stability experimental
@@ -137,21 +140,24 @@ ol.geom.Geometry.prototype.getExtent = goog.abstractMethod;
 
 
 /**
+ * @function
  * @param {number} squaredTolerance Squared tolerance.
  * @return {ol.geom.Geometry} Simplified geometry.
+ * @todo stability experimental
  */
 ol.geom.Geometry.prototype.getSimplifiedGeometry = goog.abstractMethod;
 
 
 /**
+ * @function
  * @return {ol.geom.GeometryType} Geometry type.
  * @todo stability experimental
- * @todo api
  */
 ol.geom.Geometry.prototype.getType = goog.abstractMethod;
 
 
 /**
+ * @function
  * @param {ol.TransformFunction} transformFn Transform.
  * @todo stability experimental
  */

src/ol/geom/geometrycollection.js

@@ -219,7 +219,6 @@ ol.geom.GeometryCollection.prototype.getType = function() {
 
 /**
  * @return {boolean} Is empty.
- * @todo stability experimental
  */
 ol.geom.GeometryCollection.prototype.isEmpty = function() {
   return goog.array.isEmpty(this.geometries_);

src/ol/geom/linestring.js

@@ -60,6 +60,7 @@ goog.inherits(ol.geom.LineString, ol.geom.SimpleGeometry);
 
 /**
  * @param {ol.Coordinate} coordinate Coordinate.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.LineString.prototype.appendCoordinate = function(coordinate) {
@@ -116,6 +117,7 @@ ol.geom.LineString.prototype.closestPointXY =
  * @param {number} m M.
  * @param {boolean=} opt_extrapolate Extrapolate.
  * @return {ol.Coordinate} Coordinate.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.LineString.prototype.getCoordinateAtM = function(m, opt_extrapolate) {

src/ol/geom/multilinestring.js

@@ -54,6 +54,7 @@ goog.inherits(ol.geom.MultiLineString, ol.geom.SimpleGeometry);
 
 /**
  * @param {ol.geom.LineString} lineString LineString.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.MultiLineString.prototype.appendLineString = function(lineString) {
@@ -121,6 +122,7 @@ ol.geom.MultiLineString.prototype.closestPointXY =
  * @param {boolean=} opt_extrapolate Extrapolate.
  * @param {boolean=} opt_interpolate Interpolate.
  * @return {ol.Coordinate} Coordinate.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.MultiLineString.prototype.getCoordinateAtM =
@@ -159,6 +161,7 @@ ol.geom.MultiLineString.prototype.getEnds = function() {
 /**
  * @param {number} index Index.
  * @return {ol.geom.LineString} LineString.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.MultiLineString.prototype.getLineString = function(index) {
@@ -289,7 +292,6 @@ ol.geom.MultiLineString.prototype.setFlatCoordinates =
 
 /**
  * @param {Array.<ol.geom.LineString>} lineStrings LineStrings.
- * @todo stability experimental
  */
 ol.geom.MultiLineString.prototype.setLineStrings = function(lineStrings) {
   var layout = ol.geom.GeometryLayout.XY;

src/ol/geom/multipoint.js

@@ -31,6 +31,7 @@ goog.inherits(ol.geom.MultiPoint, ol.geom.SimpleGeometry);
 
 /**
  * @param {ol.geom.Point} point Point.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.MultiPoint.prototype.appendPoint = function(point) {
@@ -96,6 +97,7 @@ ol.geom.MultiPoint.prototype.getCoordinates = function() {
 /**
  * @param {number} index Index.
  * @return {ol.geom.Point} Point.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.MultiPoint.prototype.getPoint = function(index) {

src/ol/geom/multipolygon.js

@@ -83,6 +83,7 @@ goog.inherits(ol.geom.MultiPolygon, ol.geom.SimpleGeometry);
 
 /**
  * @param {ol.geom.Polygon} polygon Polygon.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.MultiPolygon.prototype.appendPolygon = function(polygon) {
@@ -196,6 +197,7 @@ ol.geom.MultiPolygon.prototype.getFlatInteriorPoints = function() {
 
 /**
  * @return {ol.geom.MultiPoint} Interior points.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.MultiPolygon.prototype.getInteriorPoints = function() {
@@ -248,6 +250,7 @@ ol.geom.MultiPolygon.prototype.getSimplifiedGeometryInternal =
 /**
  * @param {number} index Index.
  * @return {ol.geom.Polygon} Polygon.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.MultiPolygon.prototype.getPolygon = function(index) {
@@ -364,7 +367,6 @@ ol.geom.MultiPolygon.prototype.setFlatCoordinates =
 
 /**
  * @param {Array.<ol.geom.Polygon>} polygons Polygons.
- * @todo stability experimental
  */
 ol.geom.MultiPolygon.prototype.setPolygons = function(polygons) {
   var layout = ol.geom.GeometryLayout.XY;

src/ol/geom/polygon.js

@@ -82,6 +82,7 @@ goog.inherits(ol.geom.Polygon, ol.geom.SimpleGeometry);
 
 /**
  * @param {ol.geom.LinearRing} linearRing Linear ring.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.Polygon.prototype.appendLinearRing = function(linearRing) {
@@ -184,6 +185,7 @@ ol.geom.Polygon.prototype.getFlatInteriorPoint = function() {
 
 /**
  * @return {ol.geom.Point} Interior point.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.Polygon.prototype.getInteriorPoint = function() {
@@ -194,6 +196,7 @@ ol.geom.Polygon.prototype.getInteriorPoint = function() {
 /**
  * @param {number} index Index.
  * @return {ol.geom.LinearRing} Linear ring.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.Polygon.prototype.getLinearRing = function(index) {

src/ol/geom/simplegeometry.js

@@ -103,6 +103,7 @@ ol.geom.SimpleGeometry.prototype.getExtent = function(opt_extent) {
 
 /**
  * @return {ol.Coordinate} First coordinate.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.SimpleGeometry.prototype.getFirstCoordinate = function() {
@@ -120,6 +121,7 @@ ol.geom.SimpleGeometry.prototype.getFlatCoordinates = function() {
 
 /**
  * @return {ol.Coordinate} Last point.
+ * @todo stability experimental
  * @todo api
  */
 ol.geom.SimpleGeometry.prototype.getLastCoordinate = function() {