Add documentation. Closes #1.

mjhasbach · Aug 23, 2015 · cf8ae2a · cf8ae2a
1 parent 0b46e4c
commit cf8ae2a
Show file tree

Hide file tree

Showing 5 changed files with 431 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,174 @@
-# pixi-piano-roll
+## Modules
+<dl>
+<dt><a href="#module_pixiPianoRoll">pixiPianoRoll</a></dt>
+<dd><p>JavaScript 2D WebGL / Canvas animated piano roll</p>
+</dd>
+</dl>
+## Typedefs
+<dl>
+<dt><a href="#transportTime">transportTime</a> : <code>string</code></dt>
+<dd><p>Playback position expressed in bars:quarters:sixteenths format (e.g. <code>&quot;1:2:0&quot;</code>)</p>
+</dd>
+<dt><a href="#note">note</a> : <code>string</code> | <code>number</code></dt>
+<dd><p>Musical note expressed in <a href="https://en.wikipedia.org/wiki/Scientific_pitch_notation">Scientific notation</a>, <a href="https://en.wikipedia.org/wiki/Helmholtz_pitch_notation">Helmholtz notation</a>, <a href="https://en.wikipedia.org/wiki/Piano_key_frequencies">piano key number</a>, <a href="https://en.wikipedia.org/wiki/Audio_frequency">audio frequency</a> (the closest note will be used), or <a href="https://en.wikipedia.org/wiki/MIDI">MIDI</a> note number</p>
+</dd>
+<dt><a href="#noteDuration">noteDuration</a> : <code>string</code> | <code>number</code></dt>
+<dd><p>Note duration expressed as a number (e.g. <code>1</code> for a whole note) or string (e.g. <code>&quot;4n&quot;</code> for a quarter note)</p>
+</dd>
+<dt><a href="#pianoRollAPI">pianoRollAPI</a> : <code>Object</code></dt>
+<dd><p>The piano roll API</p>
+</dd>
+</dl>
+<a name="module_pixiPianoRoll"></a>
+## pixiPianoRoll
+JavaScript 2D WebGL / Canvas animated piano roll
 
-JavaScript 2D WebGL / Canvas animated piano roll
+**Author:** Matthew Hasbach  
+**License**: MIT  
+**Copyright**: Matthew Hasbach 2015  
+<a name="exp_module_pixiPianoRoll--pixiPianoRoll"></a>
+### pixiPianoRoll(opt) ? <code>[pianoRollAPI](#pianoRollAPI)</code> ?
+Instantiate a pixiPianoRoll
+
+**Kind**: Exported function  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| opt | <code>Object</code> |  | Options object |
+| [opt.width] | <code>number</code> | <code>900</code> | Width of the piano roll |
+| [opt.height] | <code>number</code> | <code>400</code> | Height of the piano roll |
+| [opt.noteColor] | <code>number</code> &#124; <code>Object.&lt;number&gt;</code> | <code>musicalScaleColors.dDJameson</code> | Hexadecimal color of every note or object that has music note property names and hexadecimal color values. See [musical-scale-colors](https://github.com/mjhasbach/musical-scale-colors) for palettes (including the default). |
+| [opt.noteColor] | <code>number</code> | <code>0x333333</code> | Hexadecimal color of the grid lines |
+| [opt.noteColor] | <code>number</code> | <code>0</code> | Hexadecimal color of the background |
+| [opt.bpm] | <code>number</code> | <code>140</code> | Beats per minute |
+| [opt.antialias] | <code>boolean</code> | <code>true</code> | Whether or not the renderer will use antialiasing |
+| [opt.zoom] | <code>number</code> | <code>4</code> | Amount of visible measures |
+| [opt.resolution] | <code>number</code> | <code>2</code> | Amount of vertical grid lines per measure |
+| [opt.time] | <code>[transportTime](#transportTime)</code> | <code>0:0:0</code> | The [transportTime](#transportTime) at which playback will begin |
+| [opt.renderer] | <code>string</code> | <code>&quot;WebGLRenderer&quot;</code> | Determines the renderer type. Must be `"WebGLRenderer"` or `"CanvasRenderer"`. |
+| [opt.noteFormat] | <code>string</code> | <code>&quot;String&quot;</code> | The format of the [notes](#note) in `opt.noteData`. `"String"` for scientific or Helmholtz notation, `"Key"` for piano key numbers, `"Frequency"` for audio frequencies, or `"MIDI"` for MIDI note numbers. |
+| [opt.noteData] | <code>Array.&lt;Array.&lt;transportTime, note, noteDuration&gt;&gt;</code> | <code>[]</code> | See the typedefs for [transportTime](#transportTime), [note](#note), and [noteDuration](#noteDuration) |
+
+**Example**  
+```js
+var pianoRoll = pixiPianoRoll({
+    width: 900,
+    height: 400,
+    noteColor: 0xdb000f,
+    gridLineColor: 0x333333,
+    backgroundColor: 0x1a0002,
+    bpm: 140,
+    antialias: true,
+    zoom: 4,
+    resolution: 2,
+    time: '0:0:0',
+    renderer: 'WebGLRenderer',
+    noteFormat: 'String',
+    noteData: [
+        ['0:0:0', 'C4', '2n'],
+        ['0:0:0', 'D4', '2n'],
+        ['0:0:0', 'E4', '2n'],
+        ['0:2:0', 'B4', '4n'],
+        ['0:3:0', 'A#4', '4n']
+    ]
+});
+
+document.getElementsByTagName('body')[0].appendChild(pianoRoll.view);
+
+pianoRoll.playback.play();
+```
+<a name="transportTime"></a>
+## transportTime : <code>string</code>
+Playback position expressed in bars:quarters:sixteenths format (e.g. `"1:2:0"`)
+
+**Kind**: global typedef  
+<a name="note"></a>
+## note : <code>string</code> &#124; <code>number</code>
+Musical note expressed in [Scientific notation](https://en.wikipedia.org/wiki/Scientific_pitch_notation), [Helmholtz notation](https://en.wikipedia.org/wiki/Helmholtz_pitch_notation), [piano key number](https://en.wikipedia.org/wiki/Piano_key_frequencies), [audio frequency](https://en.wikipedia.org/wiki/Audio_frequency) (the closest note will be used), or [MIDI](https://en.wikipedia.org/wiki/MIDI) note number
+
+**Kind**: global typedef  
+<a name="noteDuration"></a>
+## noteDuration : <code>string</code> &#124; <code>number</code>
+Note duration expressed as a number (e.g. `1` for a whole note) or string (e.g. `"4n"` for a quarter note)
+
+**Kind**: global typedef  
+<a name="pianoRollAPI"></a>
+## pianoRollAPI : <code>Object</code>
+The piano roll API
+
+**Kind**: global typedef  
+
+* [pianoRollAPI](#pianoRollAPI) : <code>Object</code>
+  * [.playback](#pianoRollAPI.playback) : <code>Object</code>
+    * [.toggle([time])](#pianoRollAPI.playback.toggle)
+    * [.play([time])](#pianoRollAPI.playback.play)
+    * [.pause()](#pianoRollAPI.playback.pause)
+    * [.seek(time)](#pianoRollAPI.playback.seek)
+  * [.bpm](#pianoRollAPI.bpm) : <code>number</code>
+  * [.playing](#pianoRollAPI.playing) : <code>boolean</code>
+  * [.view](#pianoRollAPI.view) : <code>HTMLElement</code>
+
+<a name="pianoRollAPI.playback"></a>
+### pianoRollAPI.playback : <code>Object</code>
+Contains methods that control playback
+
+**Kind**: static property of <code>[pianoRollAPI](#pianoRollAPI)</code>  
+
+* [.playback](#pianoRollAPI.playback) : <code>Object</code>
+  * [.toggle([time])](#pianoRollAPI.playback.toggle)
+  * [.play([time])](#pianoRollAPI.playback.play)
+  * [.pause()](#pianoRollAPI.playback.pause)
+  * [.seek(time)](#pianoRollAPI.playback.seek)
+
+<a name="pianoRollAPI.playback.toggle"></a>
+#### playback.toggle([time])
+Pause if playing or play if paused
+
+**Kind**: static method of <code>[playback](#pianoRollAPI.playback)</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [time] | <code>[transportTime](#transportTime)</code> | If paused, the position to begin playing. If omitted, playback will begin at the current position. |
+
+<a name="pianoRollAPI.playback.play"></a>
+#### playback.play([time])
+Begin playback
+
+**Kind**: static method of <code>[playback](#pianoRollAPI.playback)</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [time] | <code>[transportTime](#transportTime)</code> | The position to begin playing. If omitted, playback will begin at the current position. |
+
+<a name="pianoRollAPI.playback.pause"></a>
+#### playback.pause()
+Pause playback
+
+**Kind**: static method of <code>[playback](#pianoRollAPI.playback)</code>  
+<a name="pianoRollAPI.playback.seek"></a>
+#### playback.seek(time)
+Change the playback position
+
+**Kind**: static method of <code>[playback](#pianoRollAPI.playback)</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| time | <code>[transportTime](#transportTime)</code> | The new playback position |
+
+<a name="pianoRollAPI.bpm"></a>
+### pianoRollAPI.bpm : <code>number</code>
+Change the bpm by changing this property
+
+**Kind**: static property of <code>[pianoRollAPI](#pianoRollAPI)</code>  
+<a name="pianoRollAPI.playing"></a>
+### pianoRollAPI.playing : <code>boolean</code>
+Whether or not playback is ongoing
+
+**Kind**: static property of <code>[pianoRollAPI](#pianoRollAPI)</code>  
+**Read only**: true  
+<a name="pianoRollAPI.view"></a>
+### pianoRollAPI.view : <code>HTMLElement</code>
+The piano roll canvas element
+
+**Kind**: static property of <code>[pianoRollAPI](#pianoRollAPI)</code>  
+**Read only**: true  
diff --git a/dist/pixiPianoRoll.js b/dist/pixiPianoRoll.js
@@ -7,6 +7,77 @@
     root.pixiPianoRoll = factory(root.PIXI, root.teoria, root.musicalScaleColors);
   }
 }(this, function(pixi, teoria, musicalScaleColors) {
+/**
+ * JavaScript 2D WebGL / Canvas animated piano roll
+ * @module pixiPianoRoll
+ * @author Matthew Hasbach
+ * @copyright Matthew Hasbach 2015
+ * @license MIT
+ */
+
+/**
+ * Playback position expressed in bars:quarters:sixteenths format (e.g. `"1:2:0"`)
+ * @typedef {string} transportTime
+ * @global
+ */
+
+/**
+ * Musical note expressed in [Scientific notation]{@link https://en.wikipedia.org/wiki/Scientific_pitch_notation}, [Helmholtz notation]{@link https://en.wikipedia.org/wiki/Helmholtz_pitch_notation}, [piano key number]{@link https://en.wikipedia.org/wiki/Piano_key_frequencies}, [audio frequency]{@link https://en.wikipedia.org/wiki/Audio_frequency} (the closest note will be used), or [MIDI]{@link https://en.wikipedia.org/wiki/MIDI} note number
+ * @typedef {string|number} note
+ * @global
+ */
+
+/**
+ * Note duration expressed as a number (e.g. `1` for a whole note) or string (e.g. `"4n"` for a quarter note)
+ * @typedef {string|number} noteDuration
+ * @global
+ */
+
+/**
+ * Instantiate a pixiPianoRoll
+ * @alias module:pixiPianoRoll
+ * @param {Object} opt - Options object
+ * @param {number} [opt.width=900] - Width of the piano roll
+ * @param {number} [opt.height=400] - Height of the piano roll
+ * @param {number|Object<number>} [opt.noteColor=musicalScaleColors.dDJameson] - Hexadecimal color of every note or object that has music note property names and hexadecimal color values. See [musical-scale-colors]{@link https://github.com/mjhasbach/musical-scale-colors} for palettes (including the default).
+ * @param {number} [opt.noteColor=0x333333] - Hexadecimal color of the grid lines
+ * @param {number} [opt.noteColor=0] - Hexadecimal color of the background
+ * @param {number} [opt.bpm=140] - Beats per minute
+ * @param {boolean} [opt.antialias=true] - Whether or not the renderer will use antialiasing
+ * @param {number} [opt.zoom=4] - Amount of visible measures
+ * @param {number} [opt.resolution=2] - Amount of vertical grid lines per measure
+ * @param {transportTime} [opt.time=0:0:0] - The [transportTime]{@link transportTime} at which playback will begin
+ * @param {string} [opt.renderer=WebGLRenderer] - Determines the renderer type. Must be `"WebGLRenderer"` or `"CanvasRenderer"`.
+ * @param {string} [opt.noteFormat=String] - The format of the [notes]{@link note} in `opt.noteData`. `"String"` for scientific or Helmholtz notation, `"Key"` for piano key numbers, `"Frequency"` for audio frequencies, or `"MIDI"` for MIDI note numbers.
+ * @param {Array.<Array<transportTime, note, noteDuration>>} [opt.noteData=[]] - See the typedefs for [transportTime]{@link transportTime}, [note]{@link note}, and [noteDuration]{@link noteDuration}
+ * @returns {pianoRollAPI}
+ * @example
+var pianoRoll = pixiPianoRoll({
+    width: 900,
+    height: 400,
+    noteColor: 0xdb000f,
+    gridLineColor: 0x333333,
+    backgroundColor: 0x1a0002,
+    bpm: 140,
+    antialias: true,
+    zoom: 4,
+    resolution: 2,
+    time: '0:0:0',
+    renderer: 'WebGLRenderer',
+    noteFormat: 'String',
+    noteData: [
+        ['0:0:0', 'C4', '2n'],
+        ['0:0:0', 'D4', '2n'],
+        ['0:0:0', 'E4', '2n'],
+        ['0:2:0', 'B4', '4n'],
+        ['0:3:0', 'A#4', '4n']
+    ]
+});
+
+document.getElementsByTagName('body')[0].appendChild(pianoRoll.view);
+
+pianoRoll.playback.play();
+ */
 'use strict';
 
 var _slicedToArray = (function () { function sliceIterator(arr, i) { var _arr = []; var _n = true; var _d = false; var _e = undefined; try { for (var _i = arr[Symbol.iterator](), _s; !(_n = (_s = _i.next()).done); _n = true) { _arr.push(_s.value); if (i && _arr.length === i) break; } } catch (err) { _d = true; _e = err; } finally { try { if (!_n && _i['return']) _i['return'](); } finally { if (_d) throw _e; } } return _arr; } return function (arr, i) { if (Array.isArray(arr)) { return arr; } else if (Symbol.iterator in Object(arr)) { return sliceIterator(arr, i); } else { throw new TypeError('Invalid attempt to destructure non-iterable instance'); } }; })();
@@ -367,24 +438,50 @@ function pixiPianoRoll(opt) {
 
     renderer.render(stage);
 
-    var pianoRoll = Object.defineProperties({
+    /**
+     * The piano roll API
+     * @typedef pianoRollAPI
+     * @type {Object}
+     * @global
+     */
+    var pianoRollAPI = Object.defineProperties({
+        /**
+         * Contains methods that control playback
+         * @memberof pianoRollAPI
+         * @type {Object}
+         */
         playback: {
+            /**
+             * Pause if playing or play if paused
+             * @param {transportTime} [time] - If paused, the position to begin playing. If omitted, playback will begin at the current position.
+             */
             toggle: function toggle(time) {
-                playing ? pianoRoll.playback.pause() : pianoRoll.playback.play(time);
+                playing ? pianoRollAPI.playback.pause() : pianoRollAPI.playback.play(time);
             },
+            /**
+             * Begin playback
+             * @param {transportTime} [time] - The position to begin playing. If omitted, playback will begin at the current position.
+             */
             play: function play(time) {
                 if (!playing) {
                     if (time) {
-                        pianoRoll.playback.seek(time);
+                        pianoRollAPI.playback.seek(time);
                     }
 
                     playing = true;
                     requestAnimationFrame(animate);
                 }
             },
+            /**
+             * Pause playback
+             */
             pause: function pause() {
                 playing = false;
             },
+            /**
+             * Change the playback position
+             * @param {transportTime} time - The new playback position
+             */
             seek: function seek(time) {
                 var xTime = -transportTimeToX(time),
                     xDiff = noteContainer.x - xTime;
@@ -396,21 +493,40 @@ function pixiPianoRoll(opt) {
             }
         }
     }, {
-        bpm: {
+        bpm: { /**
+                * Change the bpm by changing this property
+                * @memberof pianoRollAPI
+                * @type {number}
+                */
+
             set: function set(bpm) {
                 setBPM(bpm);
             },
             configurable: true,
             enumerable: true
         },
         playing: {
+            /**
+             * Whether or not playback is ongoing
+             * @memberof pianoRollAPI
+             * @type {boolean}
+             * @readonly
+             */
+
             get: function get() {
                 return playing;
             },
             configurable: true,
             enumerable: true
         },
         view: {
+            /**
+             * The piano roll canvas element
+             * @memberof pianoRollAPI
+             * @type {HTMLElement}
+             * @readonly
+             */
+
             get: function get() {
                 return renderer.view;
             },
@@ -419,7 +535,7 @@ function pixiPianoRoll(opt) {
         }
     });
 
-    return pianoRoll;
+    return pianoRollAPI;
 }
 return pixiPianoRoll;
 }));