ashatora/openlayers
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Greatly simplify and document the usage of JSDoc

Browse Source 
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.
This commit is contained in:
Andreas Hocevar
2014-04-13 10:43:05 +02:00
committed by Tim Schaub
parent aaf6101d0f
commit c17ac0cae3
84 changed files with 403 additions and 195 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ol/format/geojsonformat.js
+6
View File
@@ -323,6 +323,7 @@ ol.format.GeoJSON.prototype.getExtensions = function() {
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {ol.Feature} Feature.
* @todo stability experimental
* @todo api
*/
ol.format.GeoJSON.prototype.readFeature;
@@ -335,6 +336,7 @@ ol.format.GeoJSON.prototype.readFeature;
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {Array.<ol.Feature>} Features.
* @todo stability experimental
* @todo api
*/
ol.format.GeoJSON.prototype.readFeatures;
@@ -389,6 +391,7 @@ ol.format.GeoJSON.prototype.readFeaturesFromObject = function(object) {
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {ol.geom.Geometry} Geometry.
* @todo stability experimental
* @todo api
*/
ol.format.GeoJSON.prototype.readGeometry;
@@ -408,6 +411,7 @@ ol.format.GeoJSON.prototype.readGeometryFromObject = function(object) {
*
* @param {ArrayBuffer|Document|Node|Object|string} object Source.
* @return {ol.proj.Projection} Projection.
* @todo stability experimental
* @todo api
*/
ol.format.GeoJSON.prototype.readProjection = function(object) {
@@ -438,6 +442,7 @@ ol.format.GeoJSON.prototype.readProjection = function(object) {
* @function
* @param {ol.Feature} feature Feature.
* @return {ArrayBuffer|Node|Object|string} Result.
* @todo stability experimental
* @todo api
*/
ol.format.GeoJSON.prototype.writeFeature;
@@ -474,6 +479,7 @@ ol.format.GeoJSON.prototype.writeFeatureObject = function(feature) {
* @function
* @param {Array.<ol.Feature>} features Features.
* @return {ArrayBuffer|Node|Object|string} Result.
* @todo stability experimental
* @todo api
*/
ol.format.GeoJSON.prototype.writeFeatures;
src/ol/format/gmlformat.js
-1
View File
@@ -29,7 +29,6 @@ goog.require('ol.xml');
* @param {olx.format.GMLOptions=} opt_options
* Optional configuration object.
* @extends {ol.format.XMLFeature}
* @todo stability experimental
*/
ol.format.GML = function(opt_options) {
var options = /** @type {olx.format.GMLOptions} */
src/ol/format/gpxformat.js
+4 -1
View File
@@ -370,6 +370,7 @@ ol.format.GPX.WPT_PARSERS_ = ol.xml.makeParsersNS(
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {ol.Feature} Feature.
* @todo stability experimental
* @todo api
*/
ol.format.GPX.prototype.readFeature;
@@ -401,6 +402,7 @@ ol.format.GPX.prototype.readFeatureFromNode = function(node) {
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {Array.<ol.Feature>} Features.
* @todo stability experimental
* @todo api
*/
ol.format.GPX.prototype.readFeatures;
@@ -433,6 +435,7 @@ ol.format.GPX.prototype.readFeaturesFromNode = function(node) {
*
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {ol.proj.Projection} Projection.
* @todo stability experimental
* @todo api
*/
ol.format.GPX.prototype.readProjection;
@@ -795,7 +798,6 @@ ol.format.GPX.GPX_SERIALIZERS_ = ol.xml.makeStructureNS(
/**
* @constructor
* @extends {ol.format.GPX}
* @todo stability experimental
*/
ol.format.GPX.V1_1 = function() {
goog.base(this);
@@ -809,6 +811,7 @@ goog.inherits(ol.format.GPX.V1_1, ol.format.GPX);
* @function
* @param {Array.<ol.Feature>} features Features.
* @return {ArrayBuffer|Node|Object|string} Result.
* @todo stability experimental
* @todo api
*/
ol.format.GPX.prototype.writeFeatures;
src/ol/format/igcformat.js
+3
View File
@@ -92,6 +92,7 @@ ol.format.IGC.prototype.getExtensions = function() {
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {ol.Feature} Feature.
* @todo stability experimental
* @todo api
*/
ol.format.IGC.prototype.readFeature;
@@ -178,6 +179,7 @@ ol.format.IGC.prototype.readFeatureFromText = function(text) {
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {Array.<ol.Feature>} Features.
* @todo stability experimental
* @todo api
*/
ol.format.IGC.prototype.readFeatures;
@@ -202,6 +204,7 @@ ol.format.IGC.prototype.readFeaturesFromText = function(text) {
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {ol.proj.Projection} Projection.
* @todo stability experimental
* @todo api
*/
ol.format.IGC.prototype.readProjection;
src/ol/format/kmlformat.js
+3 -1
View File
@@ -1451,6 +1451,7 @@ ol.format.KML.prototype.readSharedStyleMap_ = function(node, objectStack) {
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {ol.Feature} Feature.
* @todo stability experimental
* @todo api
*/
ol.format.KML.prototype.readFeature;
@@ -1480,6 +1481,7 @@ ol.format.KML.prototype.readFeatureFromNode = function(node) {
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {Array.<ol.Feature>} Features.
* @todo stability experimental
* @todo api
*/
ol.format.KML.prototype.readFeatures;
@@ -1529,7 +1531,6 @@ ol.format.KML.prototype.readFeaturesFromNode = function(node) {
/**
* @param {Document|Node|string} source Souce.
* @return {string|undefined} Name.
* @todo stability experimental
*/
ol.format.KML.prototype.readName = function(source) {
if (ol.xml.isDocument(source)) {
@@ -1599,6 +1600,7 @@ ol.format.KML.prototype.readNameFromNode = function(node) {
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {ol.proj.Projection} Projection.
* @todo stability experimental
* @todo api
*/
ol.format.KML.prototype.readProjection;
src/ol/format/osmxmlformat.js
+1
View File
@@ -18,6 +18,7 @@ goog.require('ol.xml');
/**
* @constructor
* @extends {ol.format.XMLFeature}
* @todo stability experimental
* @todo api
*/
ol.format.OSMXML = function() {
src/ol/format/topojsonformat.js
+2
View File
@@ -272,6 +272,7 @@ ol.format.TopoJSON.readFeatureFromGeometry_ = function(object, arcs,
* @function
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {Array.<ol.Feature>} Features.
* @todo stability experimental
* @todo api
*/
ol.format.TopoJSON.prototype.readFeatures;
@@ -382,6 +383,7 @@ ol.format.TopoJSON.transformVertex_ = function(vertex, scale, translate) {
* @function
* @param {ArrayBuffer|Document|Node|Object|string} object Source.
* @return {ol.proj.Projection} Projection.
* @todo stability experimental
* @todo api
*/
ol.format.TopoJSON.prototype.readProjection = function(object) {
src/ol/format/wfsformat.js
+4
View File
@@ -93,6 +93,7 @@ ol.format.WFS.prototype.readFeaturesFromNode = function(node) {
/**
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {ol.format.WFS.TransactionResponse|undefined} Transaction response.
* @todo stability experimental
* @todo api
*/
ol.format.WFS.prototype.readTransactionResponse = function(source) {
@@ -115,6 +116,7 @@ ol.format.WFS.prototype.readTransactionResponse = function(source) {
* @param {ArrayBuffer|Document|Node|Object|string} source Source.
* @return {ol.format.WFS.FeatureCollectionMetadata|undefined}
* FeatureCollection metadata.
* @todo stability experimental
* @todo api
*/
ol.format.WFS.prototype.readFeatureCollectionMetadata = function(source) {
@@ -552,6 +554,7 @@ ol.format.WFS.writeGetFeature_ = function(node, featureTypes, objectStack) {
/**
* @param {olx.format.WFSWriteGetFeatureOptions} options Options.
* @return {Node} Result.
* @todo stability experimental
* @todo api
*/
ol.format.WFS.prototype.writeGetFeature = function(options) {
@@ -604,6 +607,7 @@ ol.format.WFS.prototype.writeGetFeature = function(options) {
* @param {Array.<ol.Feature>} deletes The features to delete.
* @param {olx.format.WFSWriteTransactionOptions} options Write options.
* @return {Node} Result.
* @todo stability experimental
* @todo api
*/
ol.format.WFS.prototype.writeTransaction = function(inserts, updates, deletes,
src/ol/format/wmscapabilitiesformat.js
+2
View File
@@ -15,6 +15,7 @@ goog.require('ol.xml');
/**
* @constructor
* @extends {ol.format.XML}
* @todo stability experimental
* @todo api
*/
ol.format.WMSCapabilities = function() {
@@ -35,6 +36,7 @@ goog.inherits(ol.format.WMSCapabilities, ol.format.XML);
* @function
* @param {Document|Node|string} source The XML source.
* @return {Object} An object representing the WMS capabilities.
* @todo stability experimental
* @todo api
*/
ol.format.WMSCapabilities.prototype.read;