Merge pull request #697 from OpenGeoscience/documentation-refactor

Improve API documentation

jsdoc.conf.json

@@ -1,7 +1,17 @@
 {
+  "opts": {
+    "template": "node_modules/jaguarjs-jsdoc"
+  },
+  "plugins": [
+    "node_modules/jsdoc-autoprivate/autoprivate.js",
+    "plugins/markdown"
+  ],
   "templates": {
+    "applicationName": "GeoJS",
+    "linenums": true,
+    "cleverLinks": true,
     "default": {
-      "useLongnameInNav": true
+      "outputSourceFiles": true
     }
   }
 }

package.json

@@ -48,9 +48,11 @@
     "istanbul-instrumenter-loader": "^0.2.0",
     "jade": "^1.11.0",
     "jade-loader": "^0.8.0",
+    "jaguarjs-jsdoc": "^1.0.2",
     "jasmine-core": "^2.4.1",
     "jquery": "~2.2.1",
     "jsdoc": "^3.4",
+    "jsdoc-autoprivate": "0.0.1",
     "json-loader": "^0.5.4",
     "karma": "^0.13.22",
     "karma-coverage": "^1.0.0",

src/camera.js

@@ -41,7 +41,8 @@
    *   * viewFromCenterSizeRotation: set the camera view based on a center
    *        point, boundary size, and rotation angle.
    *
-   * @class geo.camera
+   * @class
+   * @alias geo.camera
    * @extends geo.object
    * @param {object?} spec Options argument
    * @param {string} spec.projection One of the supported geo.camera.projection

src/event.js

@@ -8,7 +8,8 @@
  * <br>
  * The following properties are common to all event objects:
  *
- * @namespace geo.event
+ * @namespace
+ * @alias geo.event
  * @property {string} type The event type that was triggered
  * @property {object} geo A universal event object for controlling propagation
  *
@@ -83,6 +84,8 @@ geo_event.rotate = 'geo_rotate';
  * Triggered when the map is panned either by user interaction or map
  * transition.
  *
+ * @event geo.event.pan
+ * @type {object}
  * @property {object} screenDelta The number of pixels to pan the map by
  * @property {object} center The new map center
  */

src/index.js

@@ -1,3 +1,4 @@
+/** @namespace geo */
 // License headers that will be preserved in distributed bundles.
 /**
  * GeoJS

src/map.js

@@ -13,7 +13,8 @@ var sceneObject = require('./sceneObject');
  *            (center.x, center.y) + o            <-- center of viewport
  *   (-c, -c) + o                  (c, -c) + o
  *
- * @class geo.map
+ * @class
+ * @alias geo.map
  * @extends geo.sceneObject
  *
  * *** Always required ***
@@ -418,6 +419,7 @@ var map = function (arg) {
    *    clampBoundsX options (up to a point, see fix_bounds) when determining
    *    the new view.
    * @returns {geo.map}
+   * @fires geo.event.event:pan
    */
   ////////////////////////////////////////////////////////////////////////////
   this.pan = function (delta, ignoreDiscreteZoom, ignoreClampBounds) {
@@ -1504,7 +1506,8 @@ var map = function (arg) {
   ////////////////////////////////////////////////////////////////////////////
   /**
    * Get the layers contained in the map.
-   * Alias of {@linkcode geo.sceneObject.children}.
+   * Alias of {@linkcode geo.sceneObject#children}.
+   * @method
    */
   ////////////////////////////////////////////////////////////////////////////
   this.layers = this.children;

src/object.js

@@ -5,7 +5,8 @@ var inherit = require('./inherit');
 /**
  * Create a new instance of class object
  *
- * @class geo.object
+ * @class
+ * @alias geo.object
  * @extends vgl.object
  * @returns {geo.object}
  */

src/sceneObject.js

@@ -6,7 +6,8 @@ var object = require('./object');
  * Create a new instance of class sceneObject, which extends the object's
  * event handling with a tree-based event propagation.
  *
- * @class geo.sceneObject
+ * @class
+ * @alias geo.sceneObject
  * @extends geo.object
  * @returns {geo.sceneObject}
  */
@@ -55,7 +56,7 @@ var sceneObject = function (arg) {
   //////////////////////////////////////////////////////////////////////////////
   /**
    *  Get/set parent of the object
-   *  @param {?geo.sceneObject} parent
+   *  @param {geo.sceneObject} [parent]
    */
   //////////////////////////////////////////////////////////////////////////////
   this.parent = function (arg) {