Improve inline docs for Utils functions

lib/utils.js

@@ -6,9 +6,9 @@
  * Licensed under the Apache 2.0 license.
 */
 
-// Public: Monkey-patches Number to have Rails-like //seconds() function. Warning,
-// due to the way the Javascript parser works, applying functions on numbers is
-// kind of weird. See examples for details.
+// Public: Monkey-patches Number to have Rails-like //seconds() function.
+// Warning, due to the way the Javascript parser works, applying functions on
+// numbers is kind of weird. See examples for details.
 //
 // Examples
 //
@@ -20,6 +20,8 @@
 //
 //   (5).seconds()
 //   //=> 5000
+//   // This is the preferred way to represent numbers when calling these
+//   // methods on them
 //
 // Returns an integer representing time in milliseconds
 Number.prototype.seconds = function() {
@@ -45,7 +47,7 @@ Number.prototype.second = function() {
 //
 // Examples
 //
-//   5..fromScale(0, 10)
+//   (5).fromScale(0, 10)
 //   //=> 0.5
 //
 // Returns an integer representing the scaled value
@@ -60,7 +62,7 @@ Number.prototype.fromScale = function(start, end) {
 //
 // Examples
 //
-//   0.5.toScale(0, 10)
+//   (0.5).toScale(0, 10)
 //   //=> 5
 //
 // Returns an integer representing the scaled value
@@ -85,7 +87,9 @@ global.Utils = {
   //
   // Examples
   //
-  //   every 5.seconds(), -> console.log("hello world (and again in 5 seconds)!")
+  //   every((5).seconds(), function() {
+  //     console.log('Hello world (and again in 5 seconds)!');
+  //   });
   //
   // Returns an interval
   every: function every(interval, action) {
@@ -100,7 +104,9 @@ global.Utils = {
   //
   // Examples
   //
-  //   after 10.seconds(), -> console.log("hello world from ten seconds ago!")
+  //   after((10).seconds(), function() {
+  //     console.log('Hello world from ten seconds ago!');
+  //   });
   //
   // Returns an interval
   after: function after(delay, action) {
@@ -110,7 +116,9 @@ global.Utils = {
   // Public: Alias to the `every` function, but passing 0
   // Examples
   //
-  //   constantly -> console.log("hello world (and again and again)!")
+  //   constantly(function() {
+  //     console.log('hello world (and again and again)!');
+  //   });
   //
   // Returns an interval
   constantly: function constantly(action) {
@@ -121,9 +129,11 @@ global.Utils = {
   //
   // ms - number of ms to sleep for
   //
+  // Examples
+  //
+  //   sleep((1).second());
+  //
   // Returns a function
-  // Examples:
-  //   sleep 1.second()
   sleep: function sleep(ms) {
     var start = Date.now();
 
@@ -141,11 +151,12 @@ global.Utils = {
   //
   // Example
   //
-  //   var Sphero = (function(klass) {
-  //     subclass(Sphero, klass);
-  //     // Sphero is now a subclass of Parent, and can access it's methods through
-  //     // Sphero.__super__
-  //   })(Parent);
+  //    var Sphero = function Sphero() {};
+  //
+  //    subclass(Sphero, ParentClass);
+  //
+  //    // Sphero is now a subclass of Parent, and can access parent methods
+  //    // through Sphero.__super__
   //
   // Returns subclass
   subclass: function subclass(child, parent) {
@@ -220,8 +231,10 @@ global.Utils = {
   //
   //    var me = { hello: "Hello World" };
   //    var proxy = { boundMethod: function() { return this.hello; } };
+  //
   //    proxy.boundMethod = bind(proxy.boundMethod, me);
   //    proxy.boundMethod();
+  //
   //    //=> "Hello World"
   //
   // Returns a function wrapper
@@ -234,8 +247,8 @@ global.Utils = {
   //
   // Examples
   //
-  //    Cylon.Utils.bootstrap();
-  //    (after === Cylon.Utils.After) // true
+  //    Utils.bootstrap();
+  //    (after === Utils.after) // true
   //
   // Returns Cylon.Utils
   bootstrap: function bootstrap() {