diff --git a/build.py b/build.py index f84f339c7d..8621391bec 100755 --- a/build.py +++ b/build.py @@ -373,7 +373,7 @@ virtual('lint', 'build/lint-timestamp', 'build/lint-generated-timestamp', def build_lint_src_timestamp(t): t.run('%(GJSLINT)s', '--jslint_error=all', - '--custom_jsdoc_tags=todo', + '--custom_jsdoc_tags=todo,function', '--strict', t.newer(t.dependencies)) t.touch() diff --git a/src/ol/format/featureformat.js b/src/ol/format/featureformat.js index 62d7b4b4ad..06b3c4f12e 100644 --- a/src/ol/format/featureformat.js +++ b/src/ol/format/featureformat.js @@ -5,6 +5,10 @@ goog.require('goog.functions'); /** + * ol.format.Feature subclasses provide the ability to decode and encode + * {@link ol.Feature} objects from a variety of commonly used geospatial + * file formats. See the documentation for each format for more details. + * * @constructor */ ol.format.Feature = function() { @@ -24,6 +28,8 @@ ol.format.Feature.prototype.getType = goog.abstractMethod; /** + * Read a single feature from a source. + * * @param {ArrayBuffer|Document|Node|Object|string} source Source. * @return {ol.Feature} Feature. */ @@ -31,6 +37,8 @@ ol.format.Feature.prototype.readFeature = goog.abstractMethod; /** + * Read all features from a source. + * * @param {ArrayBuffer|Document|Node|Object|string} source Source. * @return {Array.} Features. */ @@ -38,6 +46,8 @@ ol.format.Feature.prototype.readFeatures = goog.abstractMethod; /** + * Read a single geometry from a source. + * * @param {ArrayBuffer|Document|Node|Object|string} source Source. * @return {ol.geom.Geometry} Geometry. */ @@ -45,6 +55,8 @@ ol.format.Feature.prototype.readGeometry = goog.abstractMethod; /** + * Read the projection from a source. + * * @param {ArrayBuffer|Document|Node|Object|string} source Source. * @return {ol.proj.Projection} Projection. */ @@ -52,6 +64,8 @@ ol.format.Feature.prototype.readProjection = goog.abstractMethod; /** + * Encode a feature in this format. + * * @param {ol.Feature} feature Feature. * @return {ArrayBuffer|Node|Object|string} Result. */ @@ -59,6 +73,8 @@ ol.format.Feature.prototype.writeFeature = goog.abstractMethod; /** + * Encode an array of features in this format. + * * @param {Array.} features Features. * @return {ArrayBuffer|Node|Object|string} Result. */ @@ -66,6 +82,8 @@ ol.format.Feature.prototype.writeFeatures = goog.abstractMethod; /** + * Write a single geometry in this format. + * * @param {ol.geom.Geometry} geometry Geometry. * @return {ArrayBuffer|Node|Object|string} Node. */ diff --git a/src/ol/format/geojsonformat.js b/src/ol/format/geojsonformat.js index 903affd392..a9e53bc413 100644 --- a/src/ol/format/geojsonformat.js +++ b/src/ol/format/geojsonformat.js @@ -21,6 +21,8 @@ goog.require('ol.proj'); /** + * Provide access to features stored in the GeoJSON format. + * * @constructor * @extends {ol.format.JSONFeature} * @param {olx.format.GeoJSONOptions=} opt_options Options. @@ -313,6 +315,28 @@ ol.format.GeoJSON.prototype.getExtensions = function() { }; +/** + * Read a feature from a GeoJSON Feature source. This method will throw + * an error if used with a FeatureCollection source. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {ol.Feature} Feature. + */ +ol.format.GeoJSON.prototype.readFeature; + + +/** + * Read all features from a GeoJSON source. Works with both Feature and + * FeatureCollection sources. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {Array.} Features. + */ +ol.format.GeoJSON.prototype.readFeatures; + + /** * @inheritDoc */ @@ -356,6 +380,16 @@ ol.format.GeoJSON.prototype.readFeaturesFromObject = function(object) { }; +/** + * Read a geometry from a GeoJSON source. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {ol.geom.Geometry} Geometry. + */ +ol.format.GeoJSON.prototype.readGeometry; + + /** * @inheritDoc */ @@ -366,7 +400,10 @@ ol.format.GeoJSON.prototype.readGeometryFromObject = function(object) { /** - * @inheritDoc + * Read the projection from the GeoJSON source file. + * + * @param {ArrayBuffer|Document|Node|Object|string} object Source. + * @return {ol.proj.Projection} Projection. */ ol.format.GeoJSON.prototype.readProjection = function(object) { var geoJSONObject = /** @type {GeoJSONObject} */ (object); @@ -390,6 +427,16 @@ ol.format.GeoJSON.prototype.readProjection = function(object) { }; +/** + * Encode a feature as a GeoJSON Feature object. + * + * @function + * @param {ol.Feature} feature Feature. + * @return {ArrayBuffer|Node|Object|string} Result. + */ +ol.format.GeoJSON.prototype.writeFeature; + + /** * @inheritDoc */ @@ -415,6 +462,16 @@ ol.format.GeoJSON.prototype.writeFeatureObject = function(feature) { }; +/** + * Encode an array of features as GeoJSON. + * + * @function + * @param {Array.} features Features. + * @return {ArrayBuffer|Node|Object|string} Result. + */ +ol.format.GeoJSON.prototype.writeFeatures; + + /** * @inheritDoc */ diff --git a/src/ol/format/gpxformat.exports b/src/ol/format/gpxformat.exports index 82582fd4ac..ac072e55dd 100644 --- a/src/ol/format/gpxformat.exports +++ b/src/ol/format/gpxformat.exports @@ -1,3 +1,5 @@ @exportSymbol ol.format.GPX @exportProperty ol.format.GPX.prototype.readFeature @exportProperty ol.format.GPX.prototype.readFeatures +@exportProperty ol.format.GPX.prototype.readProjection +@exportProperty ol.format.GPX.prototype.writeFeatures diff --git a/src/ol/format/gpxformat.js b/src/ol/format/gpxformat.js index 9217c15719..8dbe7cdba8 100644 --- a/src/ol/format/gpxformat.js +++ b/src/ol/format/gpxformat.js @@ -363,6 +363,16 @@ ol.format.GPX.WPT_PARSERS_ = ol.xml.makeParsersNS( }); +/** + * Read the first feature from a GPX source. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {ol.Feature} Feature. + */ +ol.format.GPX.prototype.readFeature; + + /** * @inheritDoc */ @@ -384,6 +394,16 @@ ol.format.GPX.prototype.readFeatureFromNode = function(node) { }; +/** + * Read all features from a GPX source. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {Array.} Features. + */ +ol.format.GPX.prototype.readFeatures; + + /** * @inheritDoc */ @@ -407,6 +427,15 @@ ol.format.GPX.prototype.readFeaturesFromNode = function(node) { }; +/** + * Read the projection from a GPX source. + * + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {ol.proj.Projection} Projection. + */ +ol.format.GPX.prototype.readProjection; + + /** * @inheritDoc */ @@ -770,6 +799,16 @@ ol.format.GPX.V1_1 = function() { goog.inherits(ol.format.GPX.V1_1, ol.format.GPX); +/** + * Encode an array of features in the GPX format. + * + * @function + * @param {Array.} features Features. + * @return {ArrayBuffer|Node|Object|string} Result. + */ +ol.format.GPX.prototype.writeFeatures; + + /** * @inheritDoc */ diff --git a/src/ol/format/igcformat.exports b/src/ol/format/igcformat.exports index f5faa5c4fb..6a6acf7e15 100644 --- a/src/ol/format/igcformat.exports +++ b/src/ol/format/igcformat.exports @@ -1,3 +1,4 @@ @exportSymbol ol.format.IGC @exportProperty ol.format.IGC.prototype.readFeature @exportProperty ol.format.IGC.prototype.readFeatures +@exportProperty ol.format.IGC.prototype.readProjection diff --git a/src/ol/format/igcformat.js b/src/ol/format/igcformat.js index 449abe3e39..8be575dd04 100644 --- a/src/ol/format/igcformat.js +++ b/src/ol/format/igcformat.js @@ -85,6 +85,16 @@ ol.format.IGC.prototype.getExtensions = function() { }; +/** + * Read the feature from the IGC source. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {ol.Feature} Feature. + */ +ol.format.IGC.prototype.readFeature; + + /** * @inheritDoc */ @@ -156,6 +166,17 @@ ol.format.IGC.prototype.readFeatureFromText = function(text) { }; +/** + * Read the feature from the source. As IGC sources contain a single + * feature, this will return the feature in an array. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {Array.} Features. + */ +ol.format.IGC.prototype.readFeatures; + + /** * @inheritDoc */ @@ -169,6 +190,16 @@ ol.format.IGC.prototype.readFeaturesFromText = function(text) { }; +/** + * Read the projection from the IGC source. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {ol.proj.Projection} Projection. + */ +ol.format.IGC.prototype.readProjection; + + /** * @inheritDoc */ diff --git a/src/ol/format/kmlformat.exports b/src/ol/format/kmlformat.exports index 72929f6fd4..edafad12f2 100644 --- a/src/ol/format/kmlformat.exports +++ b/src/ol/format/kmlformat.exports @@ -1,6 +1,5 @@ @exportSymbol ol.format.KML @exportProperty ol.format.KML.prototype.readFeature @exportProperty ol.format.KML.prototype.readFeatures -@exportProperty ol.format.KML.prototype.readGeometry @exportProperty ol.format.KML.prototype.readName @exportProperty ol.format.KML.prototype.readProjection diff --git a/src/ol/format/kmlformat.js b/src/ol/format/kmlformat.js index 7088973182..6e049f3416 100644 --- a/src/ol/format/kmlformat.js +++ b/src/ol/format/kmlformat.js @@ -1443,6 +1443,16 @@ ol.format.KML.prototype.readSharedStyleMap_ = function(node, objectStack) { }; +/** + * Read the first feature from a KML source. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {ol.Feature} Feature. + */ +ol.format.KML.prototype.readFeature; + + /** * @inheritDoc */ @@ -1462,6 +1472,16 @@ ol.format.KML.prototype.readFeatureFromNode = function(node) { }; +/** + * Read all features from a KML source. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {Array.} Features. + */ +ol.format.KML.prototype.readFeatures; + + /** * @inheritDoc */ @@ -1573,6 +1593,16 @@ ol.format.KML.prototype.readNameFromNode = function(node) { }; +/** + * Read the projection from a KML source. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {ol.proj.Projection} Projection. + */ +ol.format.KML.prototype.readProjection; + + /** * @inheritDoc */ diff --git a/src/ol/format/topojsonformat.js b/src/ol/format/topojsonformat.js index 3095cf7078..3af47c2f5c 100644 --- a/src/ol/format/topojsonformat.js +++ b/src/ol/format/topojsonformat.js @@ -264,6 +264,16 @@ ol.format.TopoJSON.readFeatureFromGeometry_ = function(object, arcs, }; +/** + * Read all features from a TopoJSON source. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} source Source. + * @return {Array.} Features. + */ +ol.format.TopoJSON.prototype.readFeatures; + + /** * @inheritDoc */ @@ -364,7 +374,11 @@ ol.format.TopoJSON.transformVertex_ = function(vertex, scale, translate) { /** - * @inheritDoc + * Read the projection from a TopoJSON source. + * + * @function + * @param {ArrayBuffer|Document|Node|Object|string} object Source. + * @return {ol.proj.Projection} Projection. */ ol.format.TopoJSON.prototype.readProjection = function(object) { return this.defaultProjection_;