From 285e1ee8743b3a9d4210aa79402a4f26a880d39e Mon Sep 17 00:00:00 2001 From: David Manthey Date: Thu, 17 May 2018 12:33:15 -0400 Subject: [PATCH] Make documentation more consistent. @typedefs must use @property not @param. Consistently use lowercase function and prefer it later in the type spec for properties and parameters. --- src/.eslintrc | 4 +++- src/d3/d3Renderer.js | 4 ++-- src/feature.js | 2 +- src/lineFeature.js | 30 ++++++++++++++-------------- src/polygonFeature.js | 32 ++++++++++++++---------------- src/quadFeature.js | 42 +++++++++++++++++++-------------------- src/tileLayer.js | 2 +- src/ui/scaleWidget.js | 46 +++++++++++++++++++++---------------------- src/ui/widget.js | 2 +- 9 files changed, 82 insertions(+), 82 deletions(-) diff --git a/src/.eslintrc b/src/.eslintrc index 9c9012b539..7e194a1817 100644 --- a/src/.eslintrc +++ b/src/.eslintrc @@ -6,7 +6,9 @@ "Number": "number", "String": "string", "Boolean": "boolean", - "bool": "boolean" + "bool": "boolean", + "Function": "function", + "func": "function" }, "prefer": { "return": "returns" diff --git a/src/d3/d3Renderer.js b/src/d3/d3Renderer.js index 40bc50e4b9..814e72a6a2 100644 --- a/src/d3/d3Renderer.js +++ b/src/d3/d3Renderer.js @@ -70,7 +70,7 @@ var d3Renderer = function (arg) { /** * Meta functions for converting from geojs styles to d3. * @private - * @param {function|object} f The style value or function to convert. + * @param {object|function} f The style value or function to convert. * @param {function} [g] An optional function that returns a boolean; if it * returns false, the style is set to `'none'`. * @returns {function} A function for converting styles. @@ -96,7 +96,7 @@ var d3Renderer = function (arg) { * Return a function for converting a size in pixels to an appropriate * d3 scale. * @private - * @param {function|object} f The style value or function to convert. + * @param {object|function} f The style value or function to convert. * @returns {function} A function for converting scale. */ this._convertScale = function (f) { diff --git a/src/feature.js b/src/feature.js index 1982418c5f..040a24eb42 100644 --- a/src/feature.js +++ b/src/feature.js @@ -34,7 +34,7 @@ var geo_event = require('./event'); * the feature. * @property {object} [style] An object that contains style values for the * feature. - * @property {function|number} [style.opacity=1] The opacity on a scale of 0 to + * @property {number|function} [style.opacity=1] The opacity on a scale of 0 to * 1. */ diff --git a/src/lineFeature.js b/src/lineFeature.js index e3efbd554c..f421888962 100644 --- a/src/lineFeature.js +++ b/src/lineFeature.js @@ -8,39 +8,39 @@ var util = require('./util'); * Line feature specification. * * @typedef {geo.feature.spec} geo.lineFeature.spec - * @param {object|Function} [position] Position of the data. Default is + * @property {object|function} [position] Position of the data. Default is * (data). - * @param {object|Function} [line] Lines from the data. Default is (data). + * @property {object|function} [line] Lines from the data. Default is (data). * Typically, the data is an array of lines, each of which is an array of * points. Only lines that have at least two points are rendered. The * position function is called for each point as `position(linePoint, * pointIndex, lineEntry, lineEntryIndex)`. - * @param {object} [style] Style object with default style options. - * @param {geo.geoColor|Function} [style.strokeColor] Color to stroke each + * @property {object} [style] Style object with default style options. + * @property {geo.geoColor|function} [style.strokeColor] Color to stroke each * line. The color can vary by point. - * @param {number|Function} [style.strokeOpacity] Opacity for each line + * @property {number|function} [style.strokeOpacity] Opacity for each line * stroke. The opacity can vary by point. Opacity is on a [0-1] scale. - * @param {number|Function} [style.strokeWidth] The weight of the line + * @property {number|function} [style.strokeWidth] The weight of the line * stroke in pixels. The width can vary by point. - * @param {number|Function} [style.strokeOffset] This is a value from -1 + * @property {number|function} [style.strokeOffset] This is a value from -1 * (left) to 1 (right), with 0 being centered. This can vary by point. - * @param {string|Function} [style.lineCap='butt'] One of 'butt', 'square', or - * 'round'. This can vary by point. - * @param {string|Function} [style.lineJoin='miter'] One of 'miter', 'bevel', - * 'round', or 'miter-clip'. This can vary by point. - * @param {boolean|Function} [style.closed=false] If true and the renderer + * @property {string|function} [style.lineCap='butt'] One of 'butt', 'square', + * or 'round'. This can vary by point. + * @property {string|function} [style.lineJoin='miter'] One of 'miter', + * 'bevel', 'round', or 'miter-clip'. This can vary by point. + * @property {boolean|function} [style.closed=false] If true and the renderer * supports it, connect the first and last points of a line if the line has * more than two points. This applies per line (if a function, it is called * with `(lineEntry, lineEntryIndex)`. - * @param {number|Function} [style.miterLimit=10] For lines of more than two + * @property {number|function} [style.miterLimit=10] For lines of more than two * segments that are mitered, if the miter length exceeds the `strokeWidth` * divided by the sine of half the angle between segments, then a bevel join * is used instead. This is a single value that applies to all lines. If a * function, it is called with `(data)`. - * @param {number|Function} [style.antialiasing] Antialiasing distance in + * @property {number|function} [style.antialiasing] Antialiasing distance in * pixels. Values must be non-negative. A value greater than 1 will produce * a visible gradient. This is a single value that applies to all lines. - * @param {string|Function} [style.debug] If 'debug', render lines in debug + * @property {string|function} [style.debug] If 'debug', render lines in debug * mode. This is a single value that applies to all lines. */ diff --git a/src/polygonFeature.js b/src/polygonFeature.js index 4e6bd40977..f06a6d4e22 100644 --- a/src/polygonFeature.js +++ b/src/polygonFeature.js @@ -7,33 +7,31 @@ var transform = require('./transform'); * Polygon feature specification. * * @typedef {geo.feature.spec} geo.polygonFeature.spec - * @param {object|Function} [position] Position of the data. Default is + * @property {object|function} [position] Position of the data. Default is * (data). - * @param {object|Function} [polygon] Polygons from the data. Default is + * @property {object|function} [polygon] Polygons from the data. Default is * (data). Typically, the data is an array of polygons, each of which is of * the form {outer: [(coordinates)], inner: [[(coordinates of first hole)], * [(coordinates of second hole)], ...]}. The inner record is optional. * Alternately, if there are no holes, a polygon can just be an array of * coordinates in the form of geo.geoPosition. The first and last point of * each polygon may be the same. - * @param {object} [style] Style object with default style options. - * @param {boolean|Function} [style.fill] True to fill polygon. Defaults to - * true. - * @param {geo.geoColor|Function} [style.fillColor] Color to fill each polygon. - * The color can vary by vertex. - * @param {number|Function} [style.fillOpacity] Opacity for each polygon. The - * opacity can vary by vertex. Opacity is on a [0-1] scale. - * @param {boolean|Function} [style.stroke] True to stroke polygon. Defaults - * to false. - * @param {geo.geoColor|Function} [style.strokeColor] Color to stroke each + * @property {object} [style] Style object with default style options. + * @property {boolean|function} [style.fill=true] True to fill polygon. + * @property {geo.geoColor|function} [style.fillColor] Color to fill each * polygon. The color can vary by vertex. - * @param {number|Function} [style.strokeOpacity] Opacity for each polygon + * @property {number|function} [style.fillOpacity] Opacity for each polygon. + * The opacity can vary by vertex. Opacity is on a [0-1] scale. + * @property {boolean|function} [style.stroke=false] True to stroke polygon. + * @property {geo.geoColor|function} [style.strokeColor] Color to stroke each + * polygon. The color can vary by vertex. + * @property {number|function} [style.strokeOpacity] Opacity for each polygon * stroke. The opacity can vary by vertex. Opacity is on a [0-1] scale. - * @param {number|Function} [style.strokeWidth] The weight of the polygon + * @property {number|function} [style.strokeWidth] The weight of the polygon * stroke in pixels. The width can vary by vertex. - * @param {boolean|Function} [style.uniformPolygon] Boolean indicating if each - * polygon has a uniform style (uniform fill color, fill opacity, stroke - * color, and stroke opacity). Defaults to false. Can vary by polygon. + * @property {boolean|function} [style.uniformPolygon=false] Boolean indicating + * if each polygon has a uniform style (uniform fill color, fill opacity, + * stroke color, and stroke opacity). Can vary by polygon. */ /** diff --git a/src/quadFeature.js b/src/quadFeature.js index ba07abc349..ae791fd158 100644 --- a/src/quadFeature.js +++ b/src/quadFeature.js @@ -6,30 +6,30 @@ var feature = require('./feature'); * Quad feature specification. * * @typedef {geo.feature.spec} geo.quadFeature.spec - * @param {geo.geoColor|Function} [color] Color for quads without images. - * Default is white ({r: 1, g: 1, b: 1}). - * @param {number|Function} [opacity=1] Opacity for the quads. - * @param {number|Function} [depth=0] Default z-coordinate for positions that - * don't explicitly specify one. - * @param {boolean|Function} [drawOnAsyncResourceLoaded=true] Redraw quads + * @property {geo.geoColor|function} [color] Color for quads without images. + * Default is white (`{r: 1, g: 1, b: 1}`). + * @property {number|function} [opacity=1] Opacity for the quads. + * @property {number|function} [depth=0] Default z-coordinate for positions + * that don't explicitly specify one. + * @property {boolean|function} [drawOnAsyncResourceLoaded=true] Redraw quads * when images or videos are loaded after initial render. - * @param {Image|string|Function} [image] Image for each data item. If + * @property {Image|string|function} [image] Image for each data item. If * falsy and `video` is also falsy, the quad is a solid color. Default is * (data).image. - * @param {HTMLVideoElement|string|Function} [video] Video for each data item. - * If falsy and `image` is also falsy, the quad is a solid color. Default is - * (data).video. - * @param {boolean|Function} [delayRenderWhenSeeking=true] If any video has a + * @property {HTMLVideoElement|string|function} [video] Video for each data + * item. If falsy and `image` is also falsy, the quad is a solid color. + * Default is (data).video. + * @property {boolean|function} [delayRenderWhenSeeking=true] If any video has a * truthy value and is seeking, delaying rendering the entire feature. This * prevents blinking when seeking a playing video, but may cause stuttering * when there are multiple videos. - * @param {geo.geoColor|Function} [previewColor=null] If specified, a color to - * show on image and video quads while waiting for the image or video to + * @property {geo.geoColor|function} [previewColor=null] If specified, a color + * to show on image and video quads while waiting for the image or video to * load. - * @param {Image|string|Function} [previewImage=null] If specified, an image to - * show on image quads while waiting for the quad-specific image to load. + * @property {Image|string|function} [previewImage=null] If specified, an image + * to show on image quads while waiting for the quad-specific image to load. * This will only be shown if it (the preview image) is already loaded. - * @param {object|Function} [position] Position of the quad. Default is + * @property {object|function} [position] Position of the quad. Default is * (data). The position is an object which specifies the corners of the * quad: ll, lr, ur, ul. At least two opposite corners must be specified. * The corners do not have to physically correspond to the order specified, @@ -41,11 +41,11 @@ var feature = require('./feature'); * triangles: (ll, lr, ul) and (ur, ul, lr). Nothing special is done for * quads that are not convex or quads that have substantially different * transformations for those two triangles. - * @param {boolean} [cacheQuads=true] If truthy, a set of internal information - * is stored on each data item in the _cachedQuad attribute. If this is - * falsy, the data item is not altered. If the data (positions, opacity, - * etc.) of individual quads will change, set this to `false` or call - * `cacheUpdate` on the data item or for all data. + * @property {boolean} [cacheQuads=true] If truthy, a set of internal + * information is stored on each data item in the _cachedQuad attribute. If + * this is falsy, the data item is not altered. If the data (positions, + * opacity, etc.) of individual quads will change, set this to `false` or + * call `cacheUpdate` on the data item or for all data. */ /** diff --git a/src/tileLayer.js b/src/tileLayer.js index 58bfd827b0..0f6c70c0ba 100644 --- a/src/tileLayer.js +++ b/src/tileLayer.js @@ -127,7 +127,7 @@ module.exports = (function () { * uses more memory but results in smoother transitions. * @param {boolean} [options.wrapX=true] Wrap in the x-direction * @param {boolean} [options.wrapY=false] Wrap in the y-direction - * @param {function|string} [options.url=null] + * @param {string|function} [options.url=null] * A function taking the current tile indices and returning a URL or jquery * ajax config to be passed to the {geo.tile} constructor. * Example: diff --git a/src/ui/scaleWidget.js b/src/ui/scaleWidget.js index 1b5f0cf9e7..5774fb4f50 100644 --- a/src/ui/scaleWidget.js +++ b/src/ui/scaleWidget.js @@ -9,29 +9,29 @@ require('./scaleWidget.styl'); * Scale widget specification. * * @typedef {object} geo.gui.scaleWidget.spec - * @param {number} [scale=1] A scale applied to the map gcs units to convert to - * the scale units. - * @param {number} [maxWidth=200] The maximum width of the scale in pixels. + * @property {number} [scale=1] A scale applied to the map gcs units to convert + * to the scale units. + * @property {number} [maxWidth=200] The maximum width of the scale in pixels. * For horizontal scales (orientation is `top` or `bottom`) this is the * maximum length of the scale bar. For vertical scales, this is the width * available for the scale text. - * @param {number} [maxHeight] The maximum height of the scale in pixels. + * @property {number} [maxHeight] The maximum height of the scale in pixels. * For vertical scales (orientation is `left` or `right`) this is the * maximum length of the scale bar. For horizontal scales, this is the * height available for the scale text. Default is 200 for vertical scales, * 20 for horizontal scales. - * @param {string} [orientation='bottom'] One of `left`, `right`, `top`, or + * @property {string} [orientation='bottom'] One of `left`, `right`, `top`, or * `bottom`. The scale text is placed in that location relative to the scale * bar. - * @param {number} [strokeWidth=2] The width of the ticks and scale bar in + * @property {number} [strokeWidth=2] The width of the ticks and scale bar in * pixels. - * @param {number} [tickLength=10] The length of the end ticks in pixels. - * @param {string|geo.gui.scaleWidget.unit[]} [units='si'] One of either 'si' - * or 'miles' or an array of units in ascending order. See the `UnitsTable` - * for examples. - * @param {Function} [distance] The function used to compute the length of the - * scale bar. This defaults to `transform.sphericalDistance` for all maps - * except those with a gcs of `'+proj=longlat +axis=enu'`, where + * @property {number} [tickLength=10] The length of the end ticks in pixels. + * @property {string|geo.gui.scaleWidget.unit[]} [units='si'] One of either + * `'si'` or `'miles'` or an array of units in ascending order. See the + * `UnitsTable` for examples. + * @property {function} [distance] The function used to compute the length of + * the scale bar. This defaults to `transform.sphericalDistance` for all + * maps except those with a gcs of `'+proj=longlat +axis=enu'`, where * `math.sqrt(util.distance2dSquared(pt1, pt2))` is used instead. */ @@ -39,16 +39,16 @@ require('./scaleWidget.styl'); * Scale widget unit specification. * * @typedef {object} geo.gui.scaleWidget.unit - * @param {string} unit Display name for the unit. - * @param {number} scale Scale for 1 unit in the current system. - * @param {number} [minimum=1] Minimum value where this applies after scaling. - * This can be used to handle singular and plural words (e.g., `[{units: - * 'meter', scale: 1}, {units: 'meters', scale: 1, minimum: 1.5}]`) - * @param {number} [basis=10] The basis for the multiples value. - * @param {object[]} [multiples] A list of objects in ascending value order that - * determine what round values are displayed. - * @param {number} multiples.multiple The value that is selected for display. - * @param {number} multiples.digit The number of significant digits in + * @property {string} unit Display name for the unit. + * @property {number} scale Scale for 1 unit in the current system. + * @property {number} [minimum=1] Minimum value where this applies after + * scaling. This can be used to handle singular and plural words (e.g., + * `[{units: 'meter', scale: 1}, {units: 'meters', scale: 1, minimum: 1.5}]`) + * @property {number} [basis=10] The basis for the multiples value. + * @property {object[]} [multiples] A list of objects in ascending value order + * that determine what round values are displayed. + * @property {number} multiples.multiple The value that is selected for display. + * @property {number} multiples.digit The number of significant digits in * `mutliple`. */ diff --git a/src/ui/widget.js b/src/ui/widget.js index 42d4f001df..75c464bb79 100644 --- a/src/ui/widget.js +++ b/src/ui/widget.js @@ -194,7 +194,7 @@ var widget = function (arg) { // specified value. Setting a property to null clears it. Setting to // undefined doesn't alter it. if (/^\s*(-|\+)?(\d+(\.\d*)?|\d*\.\d+)([eE](-|\+)?\d+)?\s*$/.test(position[cssAttr])) { - // tris ensures that the number is a float with no more than 3 + // this ensures that the number is a float with no more than 3 // decimal places (Chrome does this automatically, but doing so // explicitly makes testing more consistent). It will be an // integer when possible.