Document tree items as well, fix up a few of their documentations

Makefile

@@ -11,6 +11,6 @@ test:
 endif
 
 doc:
-	docco lib/mess/*.js
+	docco lib/mess/*.js lib/mess/tree/*.js
 
 .PHONY: test

lib/mess/tree/definition.js

@@ -12,11 +12,9 @@ tree.Definition.prototype.clone = function() {
     return obj;
 };
 
-/**
- * Return a copy of this ruleset with only
- * rules related to a specific symbolizer, but otherwise identical
- * selectors.
- */
+// Return a copy of this ruleset with only
+// rules related to a specific symbolizer, but otherwise identical
+// selectors.
 tree.Definition.prototype.filterSymbolizer = function(symbolizer) {
     var newDefinition = this.clone();
     newDefinition.rules = newDefinition.rules.filter(function(rule) {
@@ -25,6 +23,9 @@ tree.Definition.prototype.filterSymbolizer = function(symbolizer) {
     return newDefinition;
 };
 
+// Get a list of all of the symbolizer types
+// that this definition will affect as a result of
+// its rules.
 tree.Definition.prototype.symbolizers = function() {
     // reduce used to make the result of this 
     // an array of unique values.
@@ -36,10 +37,8 @@ tree.Definition.prototype.symbolizers = function() {
     }, []);
 };
 
-/**
- * Find a rule by name within this ruleset,
- * returning it if possible. Otherwise not returning.
- */
+// Find a rule by name within this ruleset,
+// returning it if possible. Otherwise not returning.
 tree.Definition.prototype.hasRule = function(name) {
     this.rules_cache = (!this.dirty && this.rules_cache)
         ? this.rules_cache
@@ -50,6 +49,9 @@ tree.Definition.prototype.hasRule = function(name) {
     return this.rules_cache[name];
 };
 
+// Take all of the rules from a given definition that 
+// this definition doesn't have already, and add them to this
+// definition.
 tree.Definition.prototype.inheritFrom = function(definition) {
     for (var i = 0; i < definition.rules.length; i++) {
         if (!this.hasRule(definition.rules[i].name)) {
@@ -59,6 +61,9 @@ tree.Definition.prototype.inheritFrom = function(definition) {
     }
 };
 
+// Get all of the unique rules in this definition, in
+// specificity order. Mapnik doesn't allow multiple attributes
+// in Symbolizers.
 tree.Definition.prototype.unique_rules = function() {
     if (this.unique_rules_cache) return this.unique_rules_cache;
     var rules = {},
@@ -73,6 +78,7 @@ tree.Definition.prototype.unique_rules = function() {
 };
 
 tree.Definition.prototype.toXML = function(env) {
+    // Return a cached compilation if one is available.
     if (this._xml) return this._xml;
 
     var sym = this.symbolizers();
@@ -86,17 +92,25 @@ tree.Definition.prototype.toXML = function(env) {
     }
 
     if (sym) {
+        // Some Mapnik symbolizers, like TextSymbolizer, don't
+        // have defaults for all properties and will fail if they
+        // aren't given. Thus, at the last minute check that these
+        // are satisfied.
         if (reqfail = tree.Reference.requiredProperties(
             sym,
             this.unique_rules())) {
             env.error({
                 message: reqfail,
-                index: this.unique_rules()[0] && this.unique_rules()[0].index,
-                index: this.unique_rules()[0] && this.unique_rules()[0].filename
+                index: this.unique_rules()[0] &&
+                    this.unique_rules()[0].index,
+                index: this.unique_rules()[0] &&
+                    this.unique_rules()[0].filename
             });
         }
     }
 
+    // Come up with a symbolizer name based on the name from
+    // Reference.
     var symname = sym ? sym.charAt(0).toUpperCase()
         + sym.slice(1).replace(/\-./, function(str) {
         return str[1].toUpperCase();

lib/mess/tree/element.js

@@ -1,13 +1,12 @@
 (function(tree) {
 
+// An element is an id or class selector
 tree.Element = function Element(value) {
     this.value = value.trim();
 };
 
-/**
- * Determine the 'specificity matrix' of this
- * specific selector
- */
+// Determine the 'specificity matrix' of this
+// specific selector
 tree.Element.prototype.specificity = function() {
     return [
         (this.value[0] == '#') ? 1 : 0, // a
@@ -19,14 +18,12 @@ tree.Element.prototype.toString = function() {
     return this.value;
 };
 
-/**
- * Determine whether this element matches an id or classes.
- * An element is a single id or class, or check whether the given
- * array of classes contains this, or the id is equal to this.
- *
- * Takes a plain string for id and plain strings in the array of
- * classes.
- */
+// Determine whether this element matches an id or classes.
+// An element is a single id or class, or check whether the given
+// array of classes contains this, or the id is equal to this.
+//
+// Takes a plain string for id and plain strings in the array of
+// classes.
 tree.Element.prototype.matches = function(id, classes) {
     return (classes.indexOf(this.value.replace(/^\./, '')) !== -1) ||
         (this.value.replace(/^#/, '') == id);

lib/mess/tree/filter.js

@@ -17,6 +17,7 @@ tree.Filter = function Filter(key, op, val, index) {
 };
 
 
+// XML-safe versions of comparators
 var opXML = {
     '<': '&lt;',
     '>': '&gt;',
@@ -26,6 +27,7 @@ var opXML = {
     '>=': '&gt;='
 };
 
+// inverses of comparators
 var opNegate = {
     '<': '>=',
     '<=': '>',
@@ -49,10 +51,8 @@ tree.Filter.prototype.toString = function() {
     return '[' + this.id + ']';
 };
 
-/**
- * Negate this filter: warning - this changes
- * the filter itself.
- */
+// Negate this filter: warning - this changes
+// the filter itself.
 tree.Filter.prototype.negate = function() {
     return new tree.Filter(this.key, opNegate[this.op], this.val);
 };
@@ -245,6 +245,8 @@ tree.Filter.simplify = function(filters) {
     return filters;
 };
 
+// Test two rules to decide whether one can be merged into the other.
+// returns the rule that the other rule can be merged into.
 tree.Filter.mergable = function(f1, f2) {
     var filters1 = Object.keys(f1);
     var filters2 = Object.keys(f2);

lib/mess/tree/zoom.js

@@ -1,10 +1,14 @@
 var tree = require('mess/tree');
 
+// Storage for zoom ranges. Only supports continuous ranges,
+// and stores them as bit-sequences so that they can be combined,
+// inverted, and compared quickly.
 tree.Zoom = function(op, value, index) {
     value = parseInt(value);
     if (value > tree.Zoom.maxZoom || value < 0) {
         throw {
-            message: 'Only zoom levels between 0 and ' + tree.Zoom.maxZoom + ' supported.',
+            message: 'Only zoom levels between 0 and '
+                + tree.Zoom.maxZoom + ' supported.',
             index: index
         };
     }
@@ -57,7 +61,7 @@ tree.Zoom.ranges = {
     23: 50
 };
 
-// Only works for single range zooms. [XXX....XXXXX.........] is invalid.
+// Only works for single range zooms. `[XXX....XXXXX.........]` is invalid.
 tree.Zoom.toXML = function(zoom) {
     var conditions = [];
     if (zoom != tree.Zoom.all) {
@@ -68,8 +72,10 @@ tree.Zoom.toXML = function(zoom) {
                 end = i;
             }
         }
-        if (start > 0) conditions.push('<MaxScaleDenominator>' + tree.Zoom.ranges[start] + '</MaxScaleDenominator>');
-        if (end < 22) conditions.push('<MinScaleDenominator>' + tree.Zoom.ranges[end + 1] + '</MinScaleDenominator>');
+        if (start > 0) conditions.push('<MaxScaleDenominator>'
+            + tree.Zoom.ranges[start] + '</MaxScaleDenominator>');
+        if (end < 22) conditions.push('<MinScaleDenominator>'
+            + tree.Zoom.ranges[end + 1] + '</MinScaleDenominator>');
     }
     return conditions;
 };