JSDoc. Fixes #1

README.md

@@ -1,5 +1,300 @@
 # point-geometry
 
-[![build status](https://secure.travis-ci.org/mapbox/point-geometry.png)](http://travis-ci.org/mapbox/point-geometry) [![Coverage Status](https://coveralls.io/repos/mapbox/point-geometry/badge.png)](https://coveralls.io/r/mapbox/point-geometry)
+[![build status](https://secure.travis-ci.org/mapbox/point-geometry.png)](http://travis-ci.org/mapbox/point-geometry)
+
+a point geometry with transforms
+
+
+### `Point(x, y)`
+
+A standalone point geometry with useful accessor, comparison, and
+modification methods.
+
+
+### Parameters
+
+| parameter | type   | description                                                                            |
+| --------- | ------ | -------------------------------------------------------------------------------------- |
+| `x`       | Number | the x-coordinate. this could be longitude or screen pixels, or any other sort of unit. |
+| `y`       | Number | the y-coordinate. this could be latitude or screen pixels, or any other sort of unit.  |
+
+
+
+### `clone`
+
+Clone this point, returning a new point that can be modified
+without affecting the old one.
+
+
+**Returns** `Point`, the clone
+
+
+### `add(p)`
+
+Add this point's x & y coordinates to another point,
+yielding a new point.
+
+### Parameters
+
+| parameter | type  | description     |
+| --------- | ----- | --------------- |
+| `p`       | Point | the other point |
+
+
+
+**Returns** `Point`, output point
+
+
+### `sub(p)`
+
+Subtract this point's x & y coordinates to from point,
+yielding a new point.
+
+### Parameters
+
+| parameter | type  | description     |
+| --------- | ----- | --------------- |
+| `p`       | Point | the other point |
+
+
+
+**Returns** `Point`, output point
+
+
+### `mult(k)`
+
+Multiply this point's x & y coordinates with from point,
+yielding a new point.
+
+### Parameters
+
+| parameter | type  | description     |
+| --------- | ----- | --------------- |
+| `k`       | Point | the other point |
+
+
+
+**Returns** `Point`, output point
+
+
+### `div(k)`
+
+Divide this point's x & y coordinates with from point,
+yielding a new point.
+
+### Parameters
+
+| parameter | type  | description     |
+| --------- | ----- | --------------- |
+| `k`       | Point | the other point |
+
+
+
+**Returns** `Point`, output point
+
+
+### `rotate(a)`
+
+Rotate this point around the 0, 0 origin by an angle a,
+given in radians
+
+### Parameters
+
+| parameter | type   | description                        |
+| --------- | ------ | ---------------------------------- |
+| `a`       | Number | angle to rotate around, in radians |
+
+
+
+**Returns** `Point`, output point
+
+
+### `matMult(m)`
+
+Multiply this point by a 4x1 transformation matrix
+
+### Parameters
+
+| parameter | type              | description           |
+| --------- | ----------------- | --------------------- |
+| `m`       | Array\.\<Number\> | transformation matrix |
+
+
+
+**Returns** `Point`, output point
+
+
+### `unit`
+
+Calculate this point but as a unit vector from 0, 0, meaning
+that the distance from the resulting point to the 0, 0
+coordinate will be equal to 1 and the angle from the resulting
+point to the 0, 0 coordinate will be the same as before.
+
+
+**Returns** `Point`, unit vector point
+
+
+### `perp`
+
+Compute a perpendicular point, where the new y coordinate
+is the old x coordinate and the new x coordinate is the old y
+coordinate multiplied by -1
+
+
+**Returns** `Point`, perpendicular point
+
+
+### `round`
+
+Return a version of this point with the x & y coordinates
+rounded to integers.
+
+
+**Returns** `Point`, rounded point
+
+
+### `mag`
+
+Return the magitude of this point: this is the Euclidean
+distance from the 0, 0 coordinate to this point's x and y
+coordinates.
+
+
+**Returns** `Number`, magnitude
+
+
+### `equals(other)`
+
+Judge whether this point is equal to another point, returning
+true or false.
+
+### Parameters
+
+| parameter | type  | description     |
+| --------- | ----- | --------------- |
+| `other`   | Point | the other point |
+
+
+
+**Returns** `boolean`, whether the points are equal
+
+
+### `dist(p)`
+
+Calculate the distance from this point to another point
+
+### Parameters
+
+| parameter | type  | description     |
+| --------- | ----- | --------------- |
+| `p`       | Point | the other point |
+
+
+
+**Returns** `Number`, distance
+
+
+### `distSqr(p)`
+
+Calculate the distance from this point to another point,
+without the square root step. Useful if you're comparing
+relative distances.
+
+### Parameters
+
+| parameter | type  | description     |
+| --------- | ----- | --------------- |
+| `p`       | Point | the other point |
+
+
+
+**Returns** `Number`, distance
+
+
+### `angle`
+
+Get the angle from the 0, 0 coordinate to this point, in radians
+coordinates.
+
+
+**Returns** `Number`, angle
+
+
+### `angleTo(b)`
+
+Get the angle from this point to another point, in radians
+
+### Parameters
+
+| parameter | type  | description     |
+| --------- | ----- | --------------- |
+| `b`       | Point | the other point |
+
+
+
+**Returns** `Number`, angle
+
+
+### `angleWith(b)`
+
+Get the angle between this point and another point, in radians
+
+### Parameters
+
+| parameter | type  | description     |
+| --------- | ----- | --------------- |
+| `b`       | Point | the other point |
+
+
+
+**Returns** `Number`, angle
+
+
+### `angleWithSep(x, y)`
+
+Find the angle of the two vectors, solving the formula for
+the cross product a x b = |a||b|sin(θ) for θ.
+
+### Parameters
+
+| parameter | type   | description      |
+| --------- | ------ | ---------------- |
+| `x`       | Number | the x-coordinate |
+| `y`       | Number | the y-coordinate |
+
+
+
+**Returns** `Number`, the angle in radians
+
+
+### `convert(a)`
+
+Construct a point from an array if necessary, otherwise if the input
+is already a Point, or an unknown type, return it unchanged
+
+### Parameters
+
+| parameter | type                     | description             |
+| --------- | ------------------------ | ----------------------- |
+| `a`       | Array\.\<Number\>\,Point | any kind of input value |
+
+
+
+**Returns** `Point`, constructed point, or passed-through value.
+
+## Installation
+
+Requires [nodejs](http://nodejs.org/).
+
+```sh
+$ npm install point-geometry
+```
+
+## Tests
+
+```sh
+$ npm test
+```
+
 
-A standalone point geometry primitive.