Skip to content

Commit

Permalink
Merge pull request #738 from OpenGeoscience/improve-docs
Browse files Browse the repository at this point in the history 
Improve jsdoc documentation.
  • Loading branch information
@manthey
manthey authored Sep 26, 2017
2 parents 86d7c11 + 1f7a330 commit 9adb694
Show file tree
Hide file tree
Showing 18 changed files with 542 additions and 321 deletions.
121 changes: 75 additions & 46 deletions src/camera.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -310,8 +310,10 @@
Object.defineProperty(this, 'viewport', {
get: function () {
return {
width: this._viewport.width, height: this._viewport.height,
left: this._viewport.left, top: this._viewport.top
width: this._viewport.width,
height: this._viewport.height,
left: this._viewport.left,
top: this._viewport.top
};
},
set: function (viewport) {
Expand Down Expand Up @@ -342,8 +344,10 @@
}

this._viewport = {
width: viewport.width, height: viewport.height,
left: viewport.left, top: viewport.top
width: viewport.width,
height: viewport.height,
left: viewport.left,
top: viewport.top
};
this._update();
this.geoTrigger(geo_event.camera.viewport, {
Expand All @@ -356,7 +360,7 @@
/**
* Reset the view matrix to its initial (identity) state.
* @protected
* @returns {this} Chainable
* @returns {this} Chainable.
*/
this._resetView = function () {
mat4.identity(this._view);
Expand All @@ -366,47 +370,49 @@
/**
* Uses `mat4.translate` to translate the camera by the given vector amount.
* @protected
* @param {vec3|Array} offset The camera translation vector
* @returns {this} Chainable
* @param {vec3|Array} offset The camera translation vector.
* @returns {this} Chainable.
*/
this._translate = function (offset) {
mat4.translate(this._view, this._view, offset);
return this;
};

/**
* Uses `mat4.scale` to scale the camera by the given vector amount.
* @protected
* @param {vec3|Array} scale The scaling vector
* @returns {this} Chainable
* @param {vec3|Array} scale The scaling vector.
* @returns {this} Chainable.
*/
this._scale = function (scale) {
mat4.scale(this._view, this._view, scale);
return this;
};

/**
* Project a vec4 from world space into clipped space [-1, 1] in place
* Project a vec4 from world space into clipped space [-1, 1] in place.
* @protected
* @param {vec4} point The point in world coordinates (mutated)
* @returns {vec4} The point in clip space coordinates
* @param {vec4} point The point in world coordinates (mutated).
* @returns {vec4} The point in clip space coordinates.
*/
this._worldToClip4 = function (point) {
return camera.applyTransform(this._transform, point);
};

/**
* Project a vec4 from clipped space into world space in place
* Project a vec4 from clipped space into world space in place.
* @protected
* @param {vec4} point The point in clipped coordinates (mutated)
* @returns {vec4} The point in world space coordinates
* @param {vec4} point The point in clipped coordinates (mutated).
* @returns {vec4} The point in world space coordinates.
*/
this._clipToWorld4 = function (point) {
return camera.applyTransform(this._inverse, point);
};

/**
* Apply the camera's projection transform to the given point.
* @param {vec4} pt a point in clipped coordinates
* @returns {vec4} the point in normalized coordinates
* @param {vec4} pt a point in clipped coordinates.
* @returns {vec4} the point in normalized coordinates.
*/
this.applyProjection = function (pt) {
var w;
Expand All @@ -424,8 +430,8 @@

/**
* Unapply the camera's projection transform from the given point.
* @param {vec4} pt a point in normalized coordinates
* @returns {vec4} the point in clipped coordinates
* @param {vec4} pt a point in normalized coordinates.
* @returns {vec4} the point in clipped coordinates.
*/
this.unapplyProjection = function (pt) {
var w;
Expand All @@ -443,8 +449,8 @@

/**
* Project a vec4 from world space into viewport space.
* @param {vec4} point The point in world coordinates (mutated)
* @returns {vec4} The point in display coordinates
* @param {vec4} point The point in world coordinates (mutated).
* @returns {vec4} The point in display coordinates.
*
* @note For the moment, this computation assumes the following:
* * point[3] > 0
Expand Down Expand Up @@ -473,8 +479,8 @@

/**
* Project a vec4 from display space into world space in place.
* @param {vec4} point The point in display coordinates (mutated)
* @returns {vec4} The point in world space coordinates
* @param {vec4} point The point in display coordinates (mutated).
* @returns {vec4} The point in world space coordinates.
*
* @note For the moment, this computation assumes the following:
* * point[3] > 0
Expand All @@ -499,10 +505,10 @@

/**
* Project a point object from world space into viewport space.
* @param {object} point The point in world coordinates
* @param {object} point The point in world coordinates.
* @param {number} point.x
* @param {number} point.y
* @returns {object} The point in display coordinates
* @returns {object} The point in display coordinates.
*/
this.worldToDisplay = function (point) {
// define some magic numbers:
Expand All @@ -516,10 +522,10 @@

/**
* Project a point object from viewport space into world space.
* @param {object} point The point in display coordinates
* @param {object} point The point in display coordinates.
* @param {number} point.x
* @param {number} point.y
* @returns {object} The point in world coordinates
* @returns {object} The point in world coordinates.
*/
this.displayToWorld = function (point) {
// define some magic numbers:
Expand All @@ -537,7 +543,7 @@
* so the result is cached for public facing methods.
*
* @protected
* @returns {object} bounds object
* @returns {object} bounds object.
*/
this._getBounds = function () {
var ul, ur, ll, lr, bds = {};
Expand Down Expand Up @@ -571,9 +577,9 @@
* @param {number} bounds.right
* @param {number} bounds.bottom
* @param {number} bounds.top
* @param {number?} bounds.near Currently ignored
* @param {number?} bounds.far Currently ignored
* @return {this} Chainable
* @param {number?} bounds.near Currently ignored.
* @param {number?} bounds.far Currently ignored.
* @returns {this} Chainable.
*/
this._setBounds = function (bounds) {
var size = {
Expand All @@ -596,14 +602,14 @@
* the viewport is a different aspect ratio.
*
* @protected
* @param {object} center
* @param {object} center Center of the view in gcs coordinates.
* @param {number} center.x
* @param {number} center.y
* @param {object} size
* @param {object} size Minimum size of the view in gcs units.
* @param {number} size.width
* @param {number} size.height
* @param {number} rotation in clockwise radians. Optional
* @return {this} Chainable
* @param {number} rotation in clockwise radians. Optional.
* @returns {this} Chainable.
*/
this._viewFromCenterSizeRotation = function (center, size, rotation) {
var translate = util.vec3AsArray(),
Expand Down Expand Up @@ -648,7 +654,19 @@
};

/**
* Public exposure of the viewFromCenterSizeRotation function.
* Sets the view matrix so that the given world center is centered, at
* least a certain width and height are visible, and a rotation is applied.
* The resulting bounds may be larger in width or height than the values if
* the viewport is a different aspect ratio.
*
* @param {object} center Center of the view in gcs coordinates.
* @param {number} center.x
* @param {number} center.y
* @param {object} size Minimum size of the view in gcs units.
* @param {number} size.width
* @param {number} size.height
* @param {number} rotation in clockwise radians. Optional.
* @returns {this} Chainable.
*/
this.viewFromCenterSizeRotation = function (center, size, rotation) {
this._viewFromCenterSizeRotation(center, size, rotation);
Expand All @@ -663,6 +681,7 @@
* @param {number} offset.x
* @param {number} offset.y
* @param {number} [offset.z=0]
* @returns {this} Chainable.
*/
this.pan = function (offset) {
if (!offset.x && !offset.y && !offset.z) {
Expand All @@ -674,12 +693,14 @@
offset.z || 0
]);
this._update();
return this;
};

/**
* Zooms the view matrix by the given amount.
*
* @param {number} zoom The zoom scale to apply
* @returns {this} Chainable.
*/
this.zoom = function (zoom) {
if (zoom === 1) {
Expand All @@ -691,14 +712,16 @@
zoom
]);
this._update();
return this;
};

/**
* Rotate the view matrix by the given amount.
*
* @param {number} rotation Counter-clockwise rotation angle in radians.
* @param {object} center Center of rotation in world space coordinates.
* @param {vec3} axis acis of rotation. Defaults to [0, 0, -1]
* @param {vec3} [axis=[0, 0, -1]] axis of rotation.
* @returns {this} Chainable.
*/
this._rotate = function (rotation, center, axis) {
if (!rotation) {
Expand All @@ -714,6 +737,7 @@
mat4.translate(this._view, this._view, center);
mat4.rotate(this._view, this._view, rotation, axis);
mat4.translate(this._view, this._view, invcenter);
return this;
};

/**
Expand Down Expand Up @@ -750,8 +774,8 @@

/**
* Represent a glmatrix as a pretty-printed string.
* @param {mat4} mat A 4 x 4 matrix
* @param {number} prec The number of decimal places
* @param {mat4} mat A 4 x 4 matrix.
* @param {number} prec The number of decimal places.
* @returns {string}
*/
this.ppMatrix = function (mat, prec) {
Expand All @@ -774,13 +798,15 @@

/**
* Pretty print the transform matrix.
* @returns {string} A string representation of the matrix.
*/
this.toString = function () {
return this.ppMatrix(this._transform);
};

/**
* Return a debugging string of the current camera state.
* @returns {string} A string with the camera state.
*/
this.debug = function () {
return [
Expand All @@ -797,6 +823,7 @@

/**
* Represent the value of the camera as its transform matrix.
* @returns {mat4} The transform matrix.
*/
this.valueOf = function () {
return this._transform;
Expand Down Expand Up @@ -841,8 +868,8 @@

/**
* Output a mat4 as a css transform.
* @param {mat4} t A matrix transform
* @returns {string} A css transform string
* @param {mat4} t A matrix transform.
* @returns {string} A css transform string.
*/
camera.css = function (t) {
return (
Expand Down Expand Up @@ -878,12 +905,14 @@
*
* applies the css transform:
*
* translate(b) scale(m) translate(a)
* translate(b) scale(m) translate(a) .
*
* If a parameter is `null` or `undefined`, that component is skipped.
*
* @param {object?} pre Coordinate offset **before** scaling
* @param {object?} scale Coordinate scaling
* @param {object?} post Coordinate offset **after** scaling
* @returns {mat4} The new transform matrix
* @param {object?} pre Coordinate offset **before** scaling.
* @param {object?} scale Coordinate scaling.
* @param {object?} post Coordinate offset **after** scaling.
* @returns {mat4} The new transform matrix.
*/
camera.affine = function (pre, scale, post) {
var mat = util.mat4AsArray();
Expand Down
5 changes: 3 additions & 2 deletions src/canvas/object.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ var sceneObject = require('../sceneObject');
* @class
* @alias geo.canvas.object
* @extends geo.sceneObject
* @param {object} arg Options for the object.
* @returns {geo.canvas.object}
*/

var canvas_object = function (arg) {
'use strict';

Expand Down Expand Up @@ -54,7 +55,7 @@ var canvas_object = function (arg) {
};

/**
* Redraw the object.
* Redraw the object.
*
* @returns {this} The current object.
*/
Expand Down
Loading

0 comments on commit 9adb694

Please sign in to comment.