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/source/bingmapssource.js

@@ -56,6 +56,7 @@ goog.inherits(ol.source.BingMaps, ol.source.TileImage);
 /**
  * @const
  * @type {ol.Attribution}
+ * @todo stability experimental
  * @todo api
  */
 ol.source.BingMaps.TOS_ATTRIBUTION = new ol.Attribution({

src/ol/source/formatvectorsource.js

@@ -23,7 +23,6 @@ goog.require('ol.xml');
  * @constructor
  * @extends {ol.source.Vector}
  * @param {olx.source.FormatVectorOptions} options Options.
- * @todo stability experimental
  */
 ol.source.FormatVector = function(options) {
 

src/ol/source/imagesource.js

@@ -25,7 +25,6 @@ ol.source.ImageOptions;
  * @constructor
  * @extends {ol.source.Source}
  * @param {ol.source.ImageOptions} options Single image source options.
- * @todo stability experimental
  */
 ol.source.Image = function(options) {
 

src/ol/source/imagewmssource.js

@@ -125,6 +125,7 @@ goog.inherits(ol.source.ImageWMS, ol.source.Image);
  *     in the `LAYERS` parameter will be used. `VERSION` should not be
  *     specified here.
  * @return {string|undefined} GetFeatureInfo URL.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.ImageWMS.prototype.getGetFeatureInfoUrl =
@@ -175,6 +176,7 @@ ol.source.ImageWMS.prototype.getGetFeatureInfoUrl =
  * Get the user-provided params, i.e. those passed to the constructor through
  * the "params" option, and possibly updated using the updateParams method.
  * @return {Object} Params.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.ImageWMS.prototype.getParams = function() {
@@ -328,6 +330,7 @@ ol.source.ImageWMS.prototype.getUrl = function() {
 
 /**
  * @param {string|undefined} url URL.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.ImageWMS.prototype.setUrl = function(url) {
@@ -342,6 +345,7 @@ ol.source.ImageWMS.prototype.setUrl = function(url) {
 /**
  * Update the user-provided params.
  * @param {Object} params Params.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.ImageWMS.prototype.updateParams = function(params) {

src/ol/source/mapguidesource.js

@@ -13,6 +13,7 @@ goog.require('ol.source.Image');
  * @constructor
  * @extends {ol.source.Image}
  * @param {olx.source.MapGuideOptions} options Options.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.MapGuide = function(options) {

src/ol/source/osmsource.js

@@ -46,6 +46,7 @@ goog.inherits(ol.source.OSM, ol.source.XYZ);
 /**
  * @const
  * @type {ol.Attribution}
+ * @todo stability experimental
  * @todo api
  */
 ol.source.OSM.DATA_ATTRIBUTION = new ol.Attribution({
@@ -59,6 +60,7 @@ ol.source.OSM.DATA_ATTRIBUTION = new ol.Attribution({
 /**
  * @const
  * @type {ol.Attribution}
+ * @todo stability experimental
  * @todo api
  */
 ol.source.OSM.TILE_ATTRIBUTION = new ol.Attribution({

src/ol/source/osmxmlsource.js

@@ -10,6 +10,7 @@ goog.require('ol.source.StaticVector');
  * @extends {ol.source.StaticVector}
  * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.OSMXMLOptions=} opt_options Options.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.OSMXML = function(opt_options) {

src/ol/source/servervectorsource.js

@@ -13,6 +13,7 @@ goog.require('ol.structs.RBush');
  * @constructor
  * @extends {ol.source.FormatVector}
  * @param {olx.source.ServerVectorOptions} options Options.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.ServerVector = function(options) {
@@ -104,6 +105,7 @@ ol.source.ServerVector.prototype.loadFeatures =
  * @function
  * @param {ArrayBuffer|Document|Node|Object|string} source Source.
  * @return {Array.<ol.Feature>} Features.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.ServerVector.prototype.readFeatures;

src/ol/source/source.js

@@ -34,7 +34,6 @@ ol.source.SourceOptions;
  * @constructor
  * @extends {ol.Observable}
  * @param {ol.source.SourceOptions} options Source options.
- * @todo stability experimental
  */
 ol.source.Source = function(options) {
 
@@ -131,6 +130,7 @@ ol.source.Source.prototype.getResolutions = goog.abstractMethod;
 
 /**
  * @return {ol.source.State} State.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.Source.prototype.getState = function() {

src/ol/source/tilesource.js

@@ -154,6 +154,7 @@ ol.source.Tile.prototype.getTile = goog.abstractMethod;
 
 /**
  * @return {ol.tilegrid.TileGrid} Tile grid.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.Tile.prototype.getTileGrid = function() {

src/ol/source/tilevectorsource.js

@@ -14,6 +14,7 @@ goog.require('ol.tilegrid.TileGrid');
  * @constructor
  * @extends {ol.source.FormatVector}
  * @param {olx.source.TileVectorOptions} options Options.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.TileVector = function(options) {
@@ -230,7 +231,6 @@ ol.source.TileVector.prototype.setTileUrlFunction = function(tileUrlFunction) {
 
 /**
  * @param {string} url URL.
- * @todo stability experimental
  */
 ol.source.TileVector.prototype.setUrl = function(url) {
   this.setTileUrlFunction(ol.TileUrlFunction.createFromTemplates(

src/ol/source/tilewmssource.js

@@ -125,6 +125,7 @@ goog.inherits(ol.source.TileWMS, ol.source.TileImage);
  *     in the `LAYERS` parameter will be used. `VERSION` should not be
  *     specified here.
  * @return {string|undefined} GetFeatureInfo URL.
+ * @todo stability experimental
  * @todo api
  */
 ol.source.TileWMS.prototype.getGetFeatureInfoUrl =

src/ol/source/vectorsource.js

@@ -149,7 +149,7 @@ ol.source.Vector.prototype.addFeaturesInternal = function(features) {
 
 
 /**
- * @todo stability experimental
+ * Clear the source
  */
 ol.source.Vector.prototype.clear = function() {
   this.rBush_.forEach(this.removeFeatureInternal, this);
@@ -181,7 +181,6 @@ ol.source.Vector.prototype.forEachFeature = function(f, opt_this) {
  * @param {T=} opt_this The object to use as `this` in `f`.
  * @return {S|undefined}
  * @template T,S
- * @todo stability experimental
  */
 ol.source.Vector.prototype.forEachFeatureAtCoordinate =
     function(coordinate, f, opt_this) {
@@ -220,7 +219,6 @@ ol.source.Vector.prototype.forEachFeatureInExtent =
  * @param {T=} opt_this The object to use as `this` in `f`.
  * @return {S|undefined}
  * @template T,S
- * @todo stability experimental
  */
 ol.source.Vector.prototype.forEachFeatureInExtentAtResolution =
     function(extent, resolution, f, opt_this) {
@@ -261,7 +259,6 @@ ol.source.Vector.prototype.getFeaturesAtCoordinate = function(coordinate) {
 /**
  * @param {ol.Extent} extent Extent.
  * @return {Array.<ol.Feature>} Features.
- * @todo stability experimental
  */
 ol.source.Vector.prototype.getFeaturesInExtent = function(extent) {
   return this.rBush_.getInExtent(extent);
@@ -354,7 +351,6 @@ ol.source.Vector.prototype.handleFeatureChange_ = function(event) {
 
 /**
  * @return {boolean} Is empty.
- * @todo stability experimental
  */
 ol.source.Vector.prototype.isEmpty = function() {
   return this.rBush_.isEmpty() &&