minor cleanup

source/Ox.js

@@ -150,9 +150,6 @@ Ox.compact <f> Returns an array w/o <code>null</code> or <code>undefined</code>
 @*/
 
 Ox.compact = function(arr) {
-    /***
-    returns an array without null or undefined values
-    ***/
     return Ox.map(arr, function(val) {
         return Ox.isUndefined(val) ? null : val;
     });
@@ -284,7 +281,7 @@ Ox.avg = function(obj) {
 };
 
 /*@
-Ox.clone <f> Returns a (shallow) copy or an object or array
+Ox.clone <f> Returns a (shallow) copy of an object or array
     > (function() { a = ['val']; b = Ox.clone(a); a[0] = null; return b[0]; }())
     'val'
     > (function() { a = {key: 'val'}; b = Ox.clone(a); a.key = null; return b.key; }())
@@ -1254,8 +1251,6 @@ Ox.getDaysInMonth <f> Get the number of days in a given month
     29
 @*/
 Ox.getDaysInMonth = function(year, month, utc) {
-    /*
-    */
     year = Ox.makeYear(year);
     month = Ox.isNumber(month) ? month :
         Ox.map(Ox.MONTHS, function(v, i) {
@@ -1264,7 +1259,7 @@ Ox.getDaysInMonth = function(year, month, utc) {
     return new Date(year, month, 0).getDate();
 }
 
-/*
+/*@
 Ox.getDaysInYear <f> Get the number of days in a given year
     > Ox.getDaysInYear(1900)
     365
@@ -1272,7 +1267,7 @@ Ox.getDaysInYear <f> Get the number of days in a given year
     366
     > Ox.getDaysInYear(new Date('01/01/2004'))
     366
-*/
+@*/
 Ox.getDaysInYear = function(year, utc) {
     return 365 + Ox.isLeapYear(Ox.makeYear(year, utc));
 };
@@ -1564,7 +1559,6 @@ Ox.documentReady = (function() {
     var callbacks = [];
     document.onreadystatechange = function() {
         if (document.readyState == 'complete') {
-            //Ox.print('document has become ready', callbacks);
             callbacks.forEach(function(callback) {
                 callback();
             });
@@ -2011,8 +2005,6 @@ Ox.element = function(str) {
         "\u00C2\u00A5\u00E2\u0082\u00AC\u0024"
     @*/
     Ox.encodeUTF8 = function(str) {
-        /*
-        */
         return Ox.map(str, function(chr) {
             var code = chr.charCodeAt(0),
                 str = '';
@@ -2041,8 +2033,6 @@ Ox.element = function(str) {
         '¥€$'
     @*/
     Ox.decodeUTF8 = function(str) {
-        /*
-        */
         var bytes = Ox.map(str, function(v) {
                 return v.charCodeAt(0);
             }),
@@ -2084,15 +2074,18 @@ Ox.element = function(str) {
 //@ Format ---------------------------------------------------------------------
 
 /*@
-Ox.formatArea <f> Formats a number of meters as square kilometers
+Ox.formatArea <f> Formats a number of meters as square meters or kilometers
+    > Ox.formatArea(1000)
+    '1,000 m\u00B2'
     > Ox.formatArea(1000000)
     '1 km\u00B2'
 @*/
 
 Ox.formatArea = function(num, dec) {
     var km = num >= 1000000;
-    return Ox.formatNumber((km ? num / 1000000 : num).toPrecision(8)) +
+    return Ox.formatNumber(
-        ' ' + (km ? 'k' : '') + 'm\u00B2';
+        (km ? num / 1000000 : num).toPrecision(8)
+    ) + ' ' + (km ? 'k' : '') + 'm\u00B2';
 }
 
 /*@
@@ -2276,7 +2269,6 @@ Ox.formatDate = function(date, str, utc) {
     return str;
 };
 
-
 /*@
 Ox.formatDateRange <f> Formats a date range as a string
     A date range is a pair of arbitrary-presicion date strings
@@ -3729,7 +3721,7 @@ Ox.deg = function(rad) {
 
 /*@
 Ox.divideInt <f> Divides a number by another and returns an array of integers
-    <code>Ox.divideInt(num, by)</code> returns an array of "as equal as
+    <code>Ox.divideInt(num, by)</code> returns a sorted array of "as equal as
     possible" integers that has a sum of <code>num</code> and a length of
     <code>by</code>.
     > Ox.divideInt(100, 3)
@@ -3738,14 +3730,12 @@ Ox.divideInt <f> Divides a number by another and returns an array of integers
     [16, 16, 17, 17, 17, 17]
 @*/
 Ox.divideInt = function(num, by) {
-    // fixme: for loops are so C ;)
     var arr = [],
         div = parseInt(num / by),
-        mod = num % by,
+        mod = num % by;
-        i;
+    Ox.loop(by, function(i) {
-    for (i = 0; i < by; i++) {
         arr[i] = div + (i > by - 1 - mod);
-    }
+    });
     return arr;
 }
 
@@ -4103,6 +4093,7 @@ Ox.isValidEmail <f> Tests if a string is a valid e-mail address
     > Ox.isValidEmail("foo@bar..com")
     false
 @*/
+// fixme: rename to isEmail
 Ox.isValidEmail = function(str) {
     return !!/^[0-9A-Z\.\+\-_]+@(?:[0-9A-Z\-]+\.)+[A-Z]{2,6}$/i(str);
 }
@@ -4249,6 +4240,8 @@ Ox.stripTags = function(str) {
 
 /*@
 Ox.substr <f> A better <code>substr</code>
+    Ox.substr behaves like str[start:stop] in Python
+    (or like str.substring() with negative values for stop)
     > Ox.substr('foobar', 1)
     "oobar"
     > Ox.substr('foobar', -1)
@@ -4262,12 +4255,9 @@ Ox.substr <f> A better <code>substr</code>
     > Ox.substr('foobar', -5, -1)
     "ooba"
 @*/
+// fixme: this would be nice to have for arrays, too
 Ox.substr = function(str, start, stop) {
-    /***
     // fixme: needed?
-    Ox.substr behaves like str[start:stop] in Python
-    (or like str.substring() with negative values for stop)
-    ***/
     stop = Ox.isUndefined(stop) ? str.length : stop;
     return str.substring(
         start < 0 ? str.length + start : start,
@@ -4284,7 +4274,6 @@ Ox.toCamelCase <f> Takes a string with '-', '/' or '_', returns a camelCase stri
     > Ox.toCamelCase('foo_bar_baz')
     'fooBarBaz'
 @*/
-
 Ox.toCamelCase = function(str) {
     return str.replace(/[\-\/_][a-z]/g, function(str) {
         return str[1].toUpperCase();
@@ -4349,7 +4338,7 @@ Ox.trim = function(str) { // is in jQuery, and in JavaScript itself
     Ox.trim(" foo ")
     "foo"
     */
-    return str.replace(/^\s+|\s+$/g, "");
+    return str.replace(/^\s+|\s+$/g, '');
 };
 
 /*@