Added lots more documentation to the parser

lib/less/parser.js

@@ -432,7 +432,22 @@ less.parser = {
                 return new(tree.Shorthand)(a, b);
             }
         },
+
+        //
+        // Mixins
+        //
         mixin: {
+            //
+            // A Mixin call, with an optional argument list
+            //
+            //     #mixins > .square(#fff);
+            //     .rounded(4px, black);
+            //     .button;
+            //
+            // The `while` loop is there because mixins can be
+            // namespaced, but we only support the child and descendant
+            // selector for now.
+            //
             call: function () {
                 var elements = [], e, c, args;
 
@@ -446,6 +461,26 @@ less.parser = {
                     return new(tree.mixin.Call)(elements, args);
                 }
             },
+
+            //
+            // A Mixin definition, with a list of parameters
+            //
+            //     .rounded (@radius: 2px, @color) {
+            //        ...
+            //     }
+            //
+            // Until we have a finer grained state-machine, we have to
+            // do a look-ahead, to make sure we don't have a mixin call.
+            // See the `rule` function for more information.
+            //
+            // We start by matching `.rounded (`, and then proceed on to
+            // the argument list, which has optional default values.
+            // We store the parameters in `params`, with a `value` key,
+            // if there is a value, such as in the case of `@radius`.
+            //
+            // Once we've got our params list, and a closing `)`, we parse
+            // the `{...}` block.
+            //
             definition: function () {
                 var name, params = [], match, ruleset, param, value;
 
@@ -494,6 +529,12 @@ less.parser = {
         end: function () {
             return $(';') || peek('}');
         },
+
+        //
+        // IE's alpha function
+        //
+        //     alpha(opacity=88)
+        //
         alpha: function () {
             var value;
 
@@ -503,6 +544,37 @@ less.parser = {
                 return new(tree.Alpha)(value);
             }
         },
+
+        //
+        // A Selector Element
+        //
+        //     div
+        //     + h1
+        //     #socks
+        //     input[type="text"]
+        //
+        // Elements are the building blocks for Selectors,
+        // they are made out of a `Combinator` (see combinator rule),
+        // and an element name, such as a tag a class, or `*`.
+        //
+        element: function () {
+            var e, t;
+
+            c = $(this.combinator);
+            e = $(/[.#:]?[a-zA-Z0-9_-]+/g) || $('*') || $(this.attribute) || $(/\([^)@]+\)/g);
+
+            if (e) { return new(tree.Element)(c, e) }
+        },
+
+        //
+        // Combinators combine elements together, in a Selector.
+        //
+        // Because our parser isn't white-space sensitive, special care
+        // has to be taken, when parsing the descendant combinator, ` `,
+        // as it's an empty space. We have to check the previous character
+        // in the input, to see if it's a ` ` character. More info on how
+        // we deal with this in *combinator.js*.
+        //
         combinator: function () {
             var match;
             if (match = $(/[+>~]/g) || $('&') || $(/::/g)) {
@@ -511,6 +583,15 @@ less.parser = {
                 return new(tree.Combinator)(input[i - 1] === " " ? " " : null);
             }
         },
+
+        //
+        // A CSS Selector
+        //
+        //     .class > div + h1
+        //     li a:hover
+        //
+        // Selectors are made out of one or more Elements, see above.
+        //
         selector: function () {
             var sel, e, elements = [], match;
 
@@ -518,14 +599,6 @@ less.parser = {
 
             if (elements.length > 0) { return new(tree.Selector)(elements) }
         },
-        element: function () {
-            var e, t;
-
-            c = $(this.combinator);
-            e = $(/[.#:]?[a-zA-Z0-9_-]+/g) || $('*') || $(this.attribute) || $(/\([^)@]+\)/g);
-
-            if (e) { return new(tree.Element)(c, e) }
-        },
         tag: function () {
             return $(/[a-zA-Z][a-zA-Z-]*[0-9]?/g) || $('*');
         },
@@ -545,6 +618,11 @@ less.parser = {
 
             if (attr) { return "[" + attr + "]" }
         },
+
+        //
+        // The `block` rule is used by `ruleset` and `mixin.definition`.
+        // It's a wrapper around the `primary` rule, with added `{}`.
+        //
         block: function () {
             var content;
 
@@ -592,6 +670,12 @@ less.parser = {
                 }
             }
         },
+
+        //
+        // A CSS Directive
+        //
+        //     @charset "utf-8";
+        //
         directive: function () {
             var name, value, rules, types;
 
@@ -628,6 +712,15 @@ less.parser = {
             }
             return new(tree.Value)(value, $(this.important));
         },
+
+        //
+        // A Value is a comma-delimited list of Expressions
+        //
+        //     font-family: Baskerville, Georgia, serif;
+        //
+        // In a Rule, a Value represents everything after the `:`,
+        // and before the `;`.
+        //
         value: function () {
             var e, expressions = [], important;
 
@@ -671,6 +764,11 @@ less.parser = {
                 }
             }
         },
+
+        //
+        // An operand is anything that can be part of an operation,
+        // such as a Color, or a Variable
+        //
         operand: function () {
             var o;
             if (o = $(this.sub) || $(this.entities.dimension) ||
@@ -679,6 +777,14 @@ less.parser = {
                 return o;
             }
         },
+
+        //
+        // Expressions either represent mathematical operations,
+        // or white-space delimited Entities.
+        //
+        //     1px solid black
+        //     @var * 2
+        //
         expression: function () {
             var e, delim, entities = [], d;