Updates README and doc comments.

Author: colinbdclark

README.md

@@ -1,29 +1,25 @@
 osc.js
 ======
 
-osc.js is a library for reading and writing [Open Sound Control](http://opensoundcontrol.org) messages in JavaScript. It has no dependencies on a particular environment or type of transport. As a result, it can be used in Node.js or in a web browser.
+osc.js is a library for reading and writing [Open Sound Control](http://opensoundcontrol.org) messages in JavaScript. It has no dependencies on the type of environment or transport used. As a result, it works both in Node.js and in a web browser.
 
 Why osc.js?
 -----------
 
-There are several other OSC libraries written in JavaScript. All of them depend on Node.js-specific APIs, which means they can't be run in a browser. osc.js uses only cross-platform APIs (specifically, `TypedArrays` and `DataView`) to ensure that it can run equally well in Node.js or in a web browser. This makes it suitable for entirely in-browser applications such as those on Chrome OS and Firefox OS.
+There are several other OSC libraries written in JavaScript. All of them depend on Node.js-specific APIs, which means they can't be run in a browser. osc.js uses only cross-platform APIs (specifically, `TypedArrays` and `DataView`) to ensure that it can run in any modern JavaScript environment.
 
 What Does it Do?
 ----------------
 
-osc.js reads and writes OSC-formatted binary data into plain JavaScript objects. It provides adaptors for reading/writing Node.js Buffer objects as well as standard ArrayBuffer objects.
+osc.js reads and writes OSC-formatted binary data into plain JavaScript objects. It provides adaptors for Node.js Buffer objects as well as standard ArrayBuffer objects.
 
 You can receive OSC data in whatever manner works best for your application: serial port APIs such as node-serialport or chrome.serial, socket APIs such as Node.js dgram or WebRTC data channels, WebSockets or binary XHR messages should all work. Connect osc.js up to your source of incoming/outgoing data, and you're all set.
 
 Status
 ------
 
-osc.js is in early, active development. It does not yet (but will) support:
+osc.js is new and still in development. It does not yet (but will) support:
 
 * Bundles
-* Time tags
-* int64 types
-* float64 types
-* char32 types
 * color types
 * MIDI types

osc.js

@@ -329,7 +329,7 @@ var osc = osc || {};
     };
 
     /**
-     * Reads an OSC time tag.
+     * Reads an OSC time tag ("t").
      *
      * @param {DataView} dv the DataView instance to read from
      * @param {Object} offsetState an offset state object containing the current index into dv
@@ -346,7 +346,17 @@ var osc = osc || {};
         };
     };
 
-    // TODO: Unit tests.
+    /**
+     * Writes an OSC time tag ("t").
+     *
+     * Takes, as its argument, a time tag object containing either a "raw" or "native property."
+     * The raw timestamp must conform to the NTP standard representation, consisting of two unsigned int32
+     * values. The first represents the number of seconds since January 1, 1900; the second, fractions of a second.
+     * "Native" JavaScript timestamps are specified as a Number representing milliseconds since January 1, 1970.
+     *
+     * @param {Object} timeTag time tag object containing either a native JS timestamp (in ms) or a NTP timestamp pair
+     * @return {Uint8Array} raw bytes for the written time tag
+     */
     osc.writeTimeTag = function (timeTag) {
         var raw = timeTag.raw ? timeTag.raw : osc.jsTimeToNTP(timeTag.native),
             arr = new Uint8Array(8), // Two Unit32s.
@@ -358,6 +368,13 @@ var osc = osc || {};
         return arr;
     };
 
+    /**
+     * Produces a time tag consisting of a JavaScript timestamp that is
+     * in the future by the specified number of seconds.
+     *
+     * @param {Number} secs the number of seconds in the future
+     * @return {Object} the time tag
+     */
     // TODO: Unit tests.
     osc.futureTimeTag = function (secs) {
         var ms = sec * 1000,
@@ -368,7 +385,14 @@ var osc = osc || {};
         };
     };
 
-    // TODO: Unit tests.
+    /**
+     * Converts OSC's standard time tag representation (which is the NTP format)
+     * into the JavaScript/UNIX format in milliseconds.
+     *
+     * @param {Number} secs1900 the number of seconds since 1900
+     * @param {Number} frac the number of fractions of a second (between 0 and 2^32)
+     * @return {Number} a JavaScript-compatible timestamp in milliseconds
+     */
     osc.ntpToJSTime = function (secs1900, frac) {
         var secs1970 = secs1900 - osc.SEVENTY_YEARS_SECS,
             ms1970 = secs1970 * 1000,
@@ -378,7 +402,12 @@ var osc = osc || {};
         return msTime;
     };
 
-    // TODO: Unit tests.
+    /**
+     * Converts a JavaScript timestamp into OSC's standard NTP timestamp format.
+     *
+     * @param {Number} jsTime the JavaScript timestamp
+     * @return {Array} a tuple consisting of the number of seconds since 1900 and the number of fractions of a second
+     */
     osc.jsTimeToNTP = function (jsTime) {
         var ms = Math.floor(jsTime),
             secs = ms / 1000,