added API docs, readme tweaks

b-g · b-g · commit f6116ed80633 · 2017-08-31T15:30:55.000+02:00
diff --git a/README.md b/README.md
@@ -1,31 +1,171 @@
-generative-design-library.js
-=============================
+# generative-design-library.js
 
 [p5.js](https://p5js.org/) library for the book [Generative Design](http://www.generative-gestaltung.de/)
 
-Developer Setup
----------------
-Download [node.js](https://nodejs.org/) or install it via [Homebrew](https://brew.sh/) (macOS only):
+## Install
 
-```
-$ brew install node
-```
+    npm install generative-design-library.js
 
-Node monitor watching on file changes:
+## API
 
-```
-$ npm run watch
-```
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
-Create a new bundle:
+### timestamp
 
-```
-$ npm run dist
-```
+Returns neatly formated timestamp e.g. "151025_172441_790"
 
-Acknowledgements
-----------------
+Returns **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** formated timestamp
 
-* ASE (Adobe Swatch Exchange) exporting is based on [node-ase-utils](https://github.com/DominikGuzei/node-ase-utils) by Dominik Guzei
-* Wacom tablet support (only Firefox and Safari) based on Wacom Plugin Table Values [Demo](http://www.wacomeng.com/web/TestFBPluginTable.html)
-* Azimuth and Altitude calculation function copy and paste from [JPEN](http://jpen.sourceforge.net/api/current/src-html/jpen/PLevel.html)
+### RED
+
+Color constant
+
+### GREEN
+
+Color constant
+
+### BLUE
+
+Color constant
+
+### HUE
+
+Color constant
+
+### SATURATION
+
+Color constant
+
+### BRIGHTNESS
+
+Color constant
+
+### GRAYSCALE
+
+Color constant
+
+### ALPHA
+
+Color constant
+
+### sortColors
+
+Sorts an array of colors according to the given method
+
+**Parameters**
+
+-   `colors` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** An array of colors.
+-   `method` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Either gd.RED, gd.GREEN, gd.BLUE, gd.HUE, gd.SATURATION, gd.BRIGHTNESS, gd.GRAYSCALE or gd.ALPHA.
+
+Returns **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** formated timestamp as string
+
+### ase.encode
+
+Returns an ase swatch definition from an array of p5 colors.
+
+**Parameters**
+
+-   `p5colors` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** an array of p5 colors
+
+Returns **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** an ase swatch definition
+
+### WacomTablet
+
+-   **See: <http://www.wacomeng.com/web/>**
+
+Use a Wacom tablet in your browser. Currently works only in Safari. Support of the Wacom browser plugin seems to be fading out. You have to add this to your html:
+
+<object id="wtPlugin" type="application/x-wacomtabletplugin"></object>
+
+#### values
+
+Get the current values a Wacom tablet
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** with properties: isWacom, isEraser, pressure, sysX, sysY, tabX, tabY, rotationDeg, rotationRad, tiltX, tiltY, tangPressure, version, pointerType, tabletModel, azimuth, altitude
+
+### Treemap
+
+Creates a new empty Treemap. Content may be added using addData() or addTreemap().
+
+**Parameters**
+
+-   `x` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** x position
+-   `y` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** y position
+-   `w` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** width
+-   `h` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** height
+-   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** drawing and sorting options {sort:true or false, direction:"horizontal", "vertical" or "both"}
+
+Returns **[Treemap](#treemap)** the created empty Treemap
+
+#### x
+
+x position of the rectangle.
+
+#### y
+
+y position of the rectangle.
+
+#### w
+
+width of the rectangle.
+
+#### h
+
+height of the rectangle.
+
+#### addData
+
+Adds one data element to the items array.
+If there is already an item which has this as data, just increase the counter of that item.
+If not, create a new Treemap with that data and init the counter with 1
+
+**Parameters**
+
+-   `data` **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array))** the data element (e.g. a String)
+
+Returns **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Returns true, if a new treemap was created
+
+#### addTreemap
+
+Adds an empty treemap to this treemap. If data is given, this could be used
+to show and hide a complete sub-treemap from the diagram. There is no check,
+if there is already another treemap with that data.
+
+**Parameters**
+
+-   `data` **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array))** the data element (e.g. a String)
+-   `count`  
+
+Returns **[Treemap](#treemap)** Returns the new Treemap
+
+#### calculate
+
+Calculates the rectangles of each item. While doing this, all counters
+and ignore flags are updated.
+
+#### draw
+
+A simple recursive drawing routine. Draws only the rectangles.
+
+## Developer Setup
+
+Download [node.js](https://nodejs.org/), then:
+
+Watch for file changes and create new bundles:
+
+    $ npm run watch
+
+Create new bundles for `dist` folder:
+
+    $ npm run dist
+
+Update API documentation:
+
+    $ npm run documentation
+
+## Acknowledgements
+
+-   ASE (Adobe Swatch Exchange) exporting is based on [node-ase-utils](https://github.com/DominikGuzei/node-ase-utils) by Dominik Guzei
+-   Wacom tablet support (only Firefox and Safari) based on Wacom Plugin Table Values [Demo](http://www.wacomeng.com/web/TestFBPluginTable.html)
+-   Azimuth and Altitude calculation function copy and paste from [JPEN](http://jpen.sourceforge.net/api/current/src-html/jpen/PLevel.html)
+-         API documentation generated with [documentation.js](https://github.com/documentationjs/)
diff --git a/Treemap.js b/Treemap.js
@@ -17,6 +17,7 @@
  * Would be nice to have...
  * TODO: Alternative constructor
  * @class Treemap
+ * @ignore
  * @constructor
  * @param  {Array} data       data to store. A plain or nested array of numbers or objects.
                               If the elements are numbers they are the counters. If objects, countkey names the key to use as a counter
@@ -26,6 +27,7 @@
 
 /**
  * @class Treemap
+ * @ignore
  * @constructor (mainly for internal use)
  * @param  {Treemap} parent   the parent Treemap
  * @param  {String|Number|Object|Array} data  one data element to store. could be anything.
@@ -35,6 +37,7 @@
 
 /**
  * @class Treemap
+ * @ignore
  * @constructor (mainly for internal use)
  * @param  {Treemap} parent   the parent Treemap
  * @return {Treemap}          the created empty Treemap
@@ -335,6 +338,8 @@ function Treemap() {
 /**
  * Randomize array element order in-place.
  * Using Durstenfeld shuffle algorithm.
+ *
+ * @ignore
  */
 function shuffleArray(array) {
   for (var i = array.length - 1; i > 0; i--) {
diff --git a/WacomTablet.js b/WacomTablet.js
@@ -3,6 +3,15 @@
 // http://www.wacomeng.com/web/
 // http://www.wacomeng.com/web/TestFBPluginTable.html
 
+/**
+ * Use a Wacom tablet in your browser. Currently works only in Safari. Support of the Wacom browser plugin seems to be fading out. You have to add this to your html:
+ *
+ * <object id="wtPlugin" type="application/x-wacomtabletplugin"></object>
+ *
+ * @see {@link http://www.wacomeng.com/web/}
+ * @class
+ * @constructor
+ */
 function WacomTablet() {
 	this.penValues = {
 		// wacom
@@ -83,6 +92,11 @@ WacomTablet.prototype._update = function() {
 	return this.penValues;
 };
 
+/**
+ * Get the current values a Wacom tablet
+ *
+ * @return {Object} with properties: isWacom, isEraser, pressure, sysX, sysY, tabX, tabY, rotationDeg, rotationRad, tiltX, tiltY, tangPressure, version, pointerType, tabletModel, azimuth, altitude
+ */
 WacomTablet.prototype.values = function() {
 	return this._update();
 };
diff --git a/color.js b/color.js
@@ -2,13 +2,46 @@
 
 var aseUtils = require('ase-utils');
 
+
+/**
+ * Color constant
+ * @property {String}
+ */
 var RED = "red";
+/**
+ * Color constant
+ * @property {String}
+ */
 var GREEN = "green";
+/**
+ * Color constant
+ * @property {String}
+ */
 var BLUE = "blue";
+/**
+ * Color constant
+ * @property {String}
+ */
 var HUE = "hue";
+/**
+ * Color constant
+ * @property {String}
+ */
 var SATURATION = "saturation";
+/**
+ * Color constant
+ * @property {String}
+ */
 var BRIGHTNESS = "brightness";
+/**
+ * Color constant
+ * @property {String}
+ */
 var GRAYSCALE = "grayscale";
+/**
+ * Color constant
+ * @property {String}
+ */
 var ALPHA = "alpha";
 
 
