Doc for Call, Comments, Operation..

lib/less/tree/call.js

@@ -1,16 +1,33 @@
 if (typeof(require) !== 'undefined') { var tree = require('less/tree') }
 
+//
+// A function call node.
+//
 tree.Call = function Call(name, args) {
     this.name = name;
     this.args = args;
 };
 tree.Call.prototype = {
     eval: function (env) { return this },
+
+    //
+    // When generating CSS from a function call,
+    // we either find the function in `tree.functions` [1],
+    // in which case we call it, passing the  evaluated arguments,
+    // or we simply print it out as it appeared originally [2].
+    //
+    // The *functions.js* file contains the built-in functions.
+    //
+    // The reason why we evaluate the arguments, is in the case where
+    // we try to pass a variable to a function, like: `saturate(@color)`.
+    // The function should receive the value, not the variable.
+    //
     toCSS: function (context, env) {
         var args = this.args.map(function (a) { return a.eval() });
-        if (this.name in tree.functions) {
+
+        if (this.name in tree.functions) { // 1.
             return tree.functions[this.name].apply(tree.functions, args).toCSS();
-        } else {
+        } else { // 2.
             return this.name +
                    "(" + args.map(function (a) { return a.toCSS() }).join(', ') + ")";
         }

lib/less/tree/color.js

@@ -3,6 +3,12 @@ if (typeof(require) !== 'undefined') { var tree = require('less/tree') }
 // RGB Colors - #ff0014, #eee
 //
 tree.Color = function Color(rgb, a) {
+    //
+    // The end goal here, is to parse the arguments
+    // into an integer triplet, such as `128, 255, 0`
+    //
+    // This facilitates operations and conversions.
+    //
     if (Array.isArray(rgb)) {
         this.rgb = rgb;
         this.alpha = a;
@@ -18,6 +24,13 @@ tree.Color = function Color(rgb, a) {
 };
 tree.Color.prototype = {
     eval: function () { return this },
+
+    //
+    // If we have some transparency, the only way to represent it
+    // is via `rgba`. Otherwise, we use the hex representation,
+    // which has better compatibility with older browsers.
+    // Values are capped between `0` and `255`, rounded and zero-padded.
+    //
     toCSS: function () {
         if (this.alpha && this.alpha < 1.0) {
             return "rgba(" + this.rgb.concat(this.alpha).join(', ') + ")";
@@ -29,8 +42,16 @@ tree.Color.prototype = {
             }).join('');
         }
     },
+
+    //
+    // Operations have to be done per-channel, if not,
+    // channels will spill onto each other. Once we have
+    // our result, in the form of an integer triplet,
+    // we create a new Color node to hold the result.
+    //
     operate: function (op, other) {
         var result = [];
+
         if (! (other instanceof tree.Color)) {
             other = other.toColor();
         }

lib/less/tree/dimension.js

@@ -1,5 +1,8 @@
 if (typeof(require) !== 'undefined') { var tree = require('less/tree') }
 
+//
+// A number with a unit
+//
 tree.Dimension = function Dimension(value, unit) {
     this.value = parseFloat(value);
     this.unit = unit || null;
@@ -14,6 +17,13 @@ tree.Dimension.prototype = {
         var css = this.value + this.unit;
         return css;
     },
+
+    // In an operation between two Dimensions,
+    // we default to the first Dimension's unit,
+    // so `1px + 2em` will yield `3px`.
+    // In the future, we could implement some unit
+    // conversions such that `100cm + 10mm` would yield
+    // `101cm`.
     operate: function (op, other) {
         return new(tree.Dimension)
                   (tree.operate(op, this.value, other.value),