Merge pull request #867 from OpenGeoscience/fix-doc-links

Make sure jsdoc links are consistent.

src/annotation.js

@@ -12,6 +12,10 @@ var textFeature = require('./textFeature');
 
 var annotationId = 0;
 
+/**
+ * @alias geo.annotation.state
+ * @enum {string}
+ */
 var annotationState = {
  create: 'create',
  done: 'done',
@@ -68,14 +72,15 @@ var editHandleFeatureLevel = 3;
  * @class
  * @alias geo.annotation
  * @param {string} type The type of annotation. These should be registered
- * with geo.registerAnnotation and can be listed with geo.listAnnotations.
+ * with {@link geo.registerAnnotation} and can be listed with
+ * {@link geo.listAnnotations}.
  * @param {object?} [args] Individual annotations have additional options.
  * @param {string} [args.name] A name for the annotation. This defaults to
  * the type with a unique ID suffixed to it.
  * @param {geo.annotationLayer} [arg.layer] A reference to the controlling
  * layer. This is used for coordinate transforms.
  * @param {string} [args.state] Initial annotation state. One of the
- * `geo.annotation.state` values.
+ * {@link geo.annotation.state} values.
  * @param {boolean|string[]} [args.showLabel=true] `true` to show the
  * annotation label on annotations in done or edit states. Alternately, a
  * list of states in which to show the label. Falsy to not show the label.
@@ -217,7 +222,7 @@ var annotation = function (type, args) {
 
  /**
  * If the label should be shown, get a record of the label that can be used
- * in a `geo.textFeature`.
+ * in a {@link geo.textFeature}.
  *
  * @returns {geo.annotationLayer.labelRecord|undefined} A label record, or
  * `undefined` if it should not be shown.
@@ -284,7 +289,7 @@ var annotation = function (type, args) {
  *
  * @param {string|undefined} arg If `undefined`, return the state,
  * otherwise change it. This should be one of the
- * `geo.annotation.state` values.
+ * {@link geo.annotation.state} values.
  * @returns {this|string} The current state or this annotation.
  * @fires geo.event.annotation.state
  */

src/annotationLayer.js

@@ -13,7 +13,7 @@ var textFeature = require('./textFeature');
  * @property {string} text The text of the label
  * @property {geo.geoPosition} position The position of the label in map gcs
  * coordinates.
- * @property {object} [style] A `geo.textFeature` style object.
+ * @property {object} [style] A {@link geo.textFeature} style object.
  */
 
 /**

src/contourFeature.js

@@ -25,7 +25,7 @@ var meshFeature = require('./meshFeature');
 
 /**
  * Contour specification. All of these properties can be functions, which get
- * passed the `geo.meshFeature.meshInfo` object.
+ * passed the {@link geo.meshFeature.meshInfo} object.
  *
  * @typedef {geo.meshFeature.meshSpec} geo.contourFeature.contourSpec
  * @property {number} [min] Minimum contour value. If unspecified, taken from

src/event.js

@@ -503,7 +503,8 @@ geo_event.annotation.select_edit_handle = 'geo_annotation_select_edit_handle';
  * selected or unselected.
  * @property {object} handle Information on the edit handle.
  * @property {boolean} action The edit action, typically one of
- * `geo.event.actiondown`, `geo.event.actionmove`, `geo.event.actionup`.
+ * {@link geo.event.actiondown}, {@link geo.event.actionmove},
+ * {@link geo.event.actionup}.
  */
 geo_event.annotation.edit_action = 'geo_annotation_edit_action';
 
@@ -531,9 +532,9 @@ geo_event.annotation.state = 'geo_annotation_state';
  * @event geo.event.annotation.mode
  * @type {object}
  * @property {string?} mode The new annotation mode. This is one of the values
- * from `geo.annotation.annotationState`.
+ * from {@link geo.annotation.state}.
  * @property {string?} oldMode The annotation mode before this change. This is
- * one of the values from `geo.annotation.annotationState`.
+ * one of the values from {@link geo.annotation.state}.
  */
 geo_event.annotation.mode = 'geo_annotation_mode';
 

src/feature.js

@@ -10,73 +10,72 @@ var geo_event = require('./event');
  * @typedef {object} geo.feature.spec
  * @property {geo.layer} [layer] the parent layer associated with the feature.
  * @property {boolean} [selectionAPI=false] If truthy, enable selection events
- *  on the feature. Selection events are those in `geo.event.feature`.
- *  They can be bound via a call like
- *  <pre><code>
- *  feature.geoOn(geo.event.feature.mousemove, function (evt) {
- *  // do something with the feature
- *  });
- *  </code></pre>
- *  where the handler is passed a `geo.feature.event` object.
+ * on the feature. Selection events are those in {@link geo.event.feature}.
+ * They can be bound via a call like
+ * ```
+ * feature.geoOn(geo.event.feature.mousemove, function (evt) {
+ * // do something with the feature
+ * });
+ * ```
+ * where the handler is passed a {@link geo.event.feature} object.
  * @property {boolean} [visible=true] If truthy, show the feature. If falsy,
- *  hide the feature and do not allow interaction with it.
+ * hide the feature and do not allow interaction with it.
  * @property {string} [gcs] The interface gcs for this feature. If `undefined`
- * or `null`, this uses the layer's interface gcs. This is a string used
- * by {@linkcode geo.transform}.
- * @property {number} [bin=0] The bin number is used to determine the order
- * of multiple features on the same layer. It has no effect except on the
- * vgl renderer. A negative value hides the feature without stopping
- * interaction with it. Otherwise, more features with higher bin numbers
- * are drawn above those with lower bin numbers. If two features have the
- * same bin number, their order relative to one another is indeterminate
- * and may be unstable.
+ * or `null`, this uses the layer's interface gcs. This is a string used by
+ * {@link geo.transform}.
+ * @property {number} [bin=0] The bin number is used to determine the order of
+ * multiple features on the same layer. It has no effect except on the vgl
+ * renderer. A negative value hides the feature without stopping interaction
+ * with it. Otherwise, more features with higher bin numbers are drawn above
+ * those with lower bin numbers. If two features have the same bin number,
+ * their order relative to one another is indeterminate and may be unstable.
  * @property {geo.renderer?} [renderer] A reference to the renderer used for
- *  the feature.
+ * the feature.
  * @property {object} [style] An object that contains style values for the
- *  feature.
+ * feature.
  * @property {number|function} [style.opacity=1] The opacity on a scale of 0 to
- *  1.
+ * 1.
  */
 
 /**
  * @typedef {geo.feature.spec} geo.feature.createSpec
  * @property {string} type A supported feature type.
  * @property {object[]} [data=[]] An array of arbitrary objects used to
- * construct the feature. These objects (and their associated indices in the
- * array) will be passed back to style and attribute accessors provided by the
- * user.
+ *  construct the feature. These objects (and their associated indices in the
+ *  array) will be passed back to style and attribute accessors provided by
+ *  the user.
  */
 
 /**
  * @typedef {geo.event} geo.feature.event
  * @property {number} index The index of the feature within the data array.
  * @property {object} data The data element associated with the indexed
- *  feature.
+ * feature.
  * @property {geo.mouseState} mouse The mouse information during the event.
  * @property {object} [extra] Additional information about the feature. This
- *  is sometimes used to identify a subsection of the feature.
+ * is sometimes used to identify a subsection of the feature.
  * @property {number} [eventID] A monotonically increasing number identifying
- *  this feature event loop. This is provided on
- *  `geo.event.feature.mousemove`, `geo.event.feature.mouseclick`,
- *  `geo.event.feature.mouseover`, `geo.event.feature.mouseout`,
- *  `geo.event.feature.brush`, and `geo.event.feature.brushend`
- *  events, since each of those can trigger multiple events for one mouse
- *  action (all events triggered by the same mouse action will have the
- *  same `eventID`).
+ * this feature event loop. This is provided on
+ * {@link geo.event.feature.mousemove}, {@link geo.event.feature.mouseclick},
+ * {@link geo.event.feature.mouseover}, {@link geo.event.feature.mouseout},
+ * {@link geo.event.feature.brush}, and {@link geo.event.feature.brushend}
+ * events, since each of those can trigger multiple events for one mouse
+ * action (all events triggered by the same mouse action will have the same
+ * `eventID`).
  * @property {boolean} [top] `true` if this is the top-most feature that the
- *  mouse is over. Only the top-most feature gets
- *  `geo.event.feature.mouseon` events, whereas multiple features can get
- *   other events.
+ * mouse is over. Only the top-most feature gets
+ * {@link geo.event.feature.mouseon} events, whereas multiple features can
+ * get other events.
  */
 
 /**
  * @typedef {object} geo.feature.searchResult
  * @property {object[]} found A list of elements from the data array that were
- *  found by the search.
+ * found by the search.
  * @property {number[]} index A list of the indices of the elements that were
- *  found by the search.
+ * found by the search.
  * @property {object[]} [extra] A list of additional information per found
- *  element. The information is passed to events without change.
+ * element. The information is passed to events without change.
  */
 
 /**
@@ -473,8 +472,8 @@ var feature = function (arg) {
  /**
  * Set style(s) from array(s). For each style, the array should have one
  * value per data item. The values are not converted or validated. Color
- * values should be `geo.geoColorObject`s. If invalid values are given the
- * behavior is undefined.
+ * values should be {@link geo.geoColorObject}s. If invalid values are given
+ * the behavior is undefined.
  * For some feature styles, if the first entry of an array is itself an
  * array, then each entry of the array is expected to be an array, and values
  * are used from these subarrays. This allows a style to apply, for
@@ -554,7 +553,7 @@ var feature = function (arg) {
  * @param {string?} [val] If `undefined`, return the current gcs. If
  * `null`, use the map's interface gcs. Otherwise, set a new value for
  * the gcs.
- * @returns {string|this} A string used by {@linkcode geo.transform}. If the
+ * @returns {string|this} A string used by {@link geo.transform}. If the
  * map interface gcs is in use, that value will be returned. If the gcs
  * is set, return the current class instance.
  */
@@ -771,7 +770,7 @@ var feature = function (arg) {
  * will make it so that the mouseon events prefer the highest index feature.
  *
  * @param {geo.event} evt The event; this should be triggered from
- * `geo.event.feature.mouseover_order`.
+ * {@link geo.event.feature.mouseover_order}.
  */
  this.mouseOverOrderHighestIndex = function (evt) {
  // sort the found indices. The last one is the one "on top".
@@ -833,7 +832,7 @@ var feature = function (arg) {
 };
 
 /**
- * The most recent `geo.feature.event` triggered.
+ * The most recent {@link geo.feature.event} triggered.
  * @type {number}
  */
 feature.eventID = 0;

src/isolineFeature.js

@@ -10,8 +10,8 @@ var util = require('./util');
  * @property {object[]} [data=[]] An array of arbitrary objects used to
  * construct the feature.
  * @property {object} [style] An object that contains style values for the
- * feature. This includes `geo.lineFeature` and `geo.textFeature` style
- * values.
+ * feature. This includes {@link geo.lineFeature} and
+ * {@link geo.textFeature} style values.
  * @property {number|function} [style.opacity=1] Overall opacity on a scale of
  * 0 to 1.
  * @property {geo.geoPosition|function} [style.position=data] The position of
@@ -44,7 +44,7 @@ var util = require('./util');
 
 /**
  * Isoline specification. All of these properties can be functions, which get
- * passed the `geo.meshFeature.meshInfo` object.
+ * passed the {@link geo.meshFeature.meshInfo} object.
  *
  * @typedef {geo.meshFeature.meshSpec} geo.isolineFeature.isolineSpec
  * @property {number} [min] Minimum isoline value. If unspecified, taken from
@@ -89,7 +89,7 @@ var util = require('./util');
  * is panned (including zoom, rotation, etc.), periodically regenerate
  * labels. This uses an internal function that has a threshold based on a
  * fixed change in zoom, size, and other parameters. Set `labelAutoUpdate`
- * to `false` and handle the `geo.event.pan` elsewhere.
+ * to `false` and handle the {@link geo.event.pan} elsewhere.
  */
 
 /**

src/map.js

@@ -334,7 +334,7 @@ var map = function (arg) {
  *
  * @param {string} [arg] If `undefined`, return the current gcs. Otherwise,
  * a new value for the gcs.
- * @returns {string|this} A string used by {@linkcode geo.transform}.
+ * @returns {string|this} A string used by {@link geo.transform}.
  */
  this.gcs = function (arg) {
  if (arg === undefined) {
@@ -359,7 +359,7 @@ var map = function (arg) {
  *
  * @param {string} [arg] If `undefined`, returtn the current interface gcs.
  * Otherwise, a new value for the interface gcs.
- * @returns {string|this} A string used by {@linkcode geo.transform}.
+ * @returns {string|this} A string used by {@link geo.transform}.
  */
  this.ingcs = function (arg) {
  if (arg === undefined) {
@@ -1515,7 +1515,7 @@ var map = function (arg) {
 
  /**
  * Get the layers contained in the map.
- * Alias of {@linkcode geo.sceneObject#children}.
+ * Alias of {@link geo.sceneObject#children}.
  * @method
  */
  this.layers = this.children;
@@ -1527,8 +1527,8 @@ var map = function (arg) {
  * attribution notices into a single element. By default, this method
  * is called on each of the following events:
  *
- * * geo.event.layerAdd
- * * geo.event.layerRemove
+ * * {@link geo.event.layerAdd}
+ * * {@link geo.event.layerRemove}
  *
  * In addition, layers should call this method when their own attribution
  * notices have changed. Users, in general, should not need to call this.

src/osmLayer.js

@@ -8,8 +8,8 @@ module.exports = (function () {
  var quadFeature = require('./quadFeature');
 
  /**
- * Create a new instance of osmLayer. This is a `geo.tileLayer` with an
- * OSM url and attribution defaults and with the tiles centered on the
+ * Create a new instance of osmLayer. This is a [@link geo.tileLayer} with
+ * an OSM url and attribution defaults and with the tiles centered on the
  * origin.
  *
  * @class

src/polygonFeature.js

@@ -186,7 +186,7 @@ var polygonFeature = function (arg) {
  * @param {object|function} [val] If not specified, return the current
  * polygon accessor. If specified, use this for the polygon accessor and
  * return `this`. If a function is given, the function is passed
- * `(dataElement, dataIndex)` and returns a `geo.polygon`.
+ * `(dataElement, dataIndex)` and returns a {@link geo.polygon}.
  * @returns {object|function|this} The current polygon accessor or this
  * feature.
  */
@@ -498,7 +498,7 @@ var polygonFeature = function (arg) {
  * closet border, including hole edges.
  *
  * @param {geo.event} evt The event; this should be triggered from
- * `geo.event.feature.mouseover_order`.
+ * {@link geo.event.feature.mouseover_order}.
  */
  this.mouseOverOrderClosestBorder = function (evt) {
  var data = evt.feature.data(),

src/tile.js

@@ -8,10 +8,9 @@ module.exports = (function () {
  * defined as a rectangular section of a map. The base implementation
  * is independent of the actual content of the tile, but assumes that
  * the content is loaded asynchronously via a url. The tile object
- * has a promise-like interface. For example,
- * ```
+ * has a promise-like interface.
+ * @example
  * tile.then(function (data) {...}).catch(function (data) {...});
- * ```.
  *
  * @class
  * @alias geo.tile

src/tileLayer.js

@@ -80,10 +80,10 @@ module.exports = (function () {
  /**
  * This method defines a tileLayer, an abstract class defining a layer
  * divided into tiles of arbitrary data. Notably, this class provides the
- * core functionality of `geo.osmLayer`, but hooks exist to render tiles more
- * generically. When multiple zoom levels are present in a given dataset,
- * this class assumes that the space occupied by tile `(i, j)` at level `z`
- * is covered by a 2x2 grid of tiles at zoom level `z + 1`:
+ * core functionality of {@link geo.osmLayer}, but hooks exist to render
+ * tiles more generically. When multiple zoom levels are present in a given
+ * dataset, this class assumes that the space occupied by tile `(i, j)` at
+ * level `z` is covered by a 2x2 grid of tiles at zoom level `z + 1`:
  * ```
  * (2i, 2j), (2i, 2j + 1)
  * (2i + 1, 2j), (2i + 1, 2j + 1)

src/transform.js

@@ -470,9 +470,9 @@ transform.affineForward = function (def, coords) {
 };
 
 /**
- * Apply an inverse affine transformation which is the inverse to {@link
- * geo.transform.affineForward}. Note, the transformation occurs in place so
- * the input coordinate object are mutated.
+ * Apply an inverse affine transformation which is the inverse to
+ * {@link geo.transform.affineForward}. Note, the transformation occurs in
+ * place so the input coordinate object are mutated.
  *
  * @param {object} def
  * @param {geo.geoPosition} def.origin The transformed origin

src/util/throttle.js

@@ -51,7 +51,7 @@
  * this method is used to accumulate values that the callback uses
  * when it finally executes.
  * @param {boolean} [debounce_mode] See the `at_begin` parameter of the
- * `geo.util.debounce` function.
+ * {@link geo.util.debounce} function.
  * @returns {function} The throttled version of `callback`.
  *
  * @example
@@ -168,7 +168,7 @@ var throttle = function (delay, no_trailing, callback, accumulator, debounce_mod
  * ||||||||||||||||||||||||| (pause) |||||||||||||||||||||||||
  * X X
  *
- * The bulk of the work is handled by the `geo.util.throttle` function.
+ * The bulk of the work is handled by the {@link geo.util.throttle} function.
  *
  * @param {number} delay A zero-or-greater delay in milliseconds. For event
  * callbacks, values around 100 or 250 (or even higher) are most useful.