From 4ea76f1d2e9e6f9308d2c642327289beae2fc258 Mon Sep 17 00:00:00 2001 From: Richard Fairhurst Date: Thu, 12 Jul 2012 17:44:40 +0100 Subject: [PATCH] Documentation for styleparser (not quite complete but this is taken from P2 anyway) --- js/iD/styleparser/Condition.js | 2 ++ js/iD/styleparser/Rule.js | 15 +++++++-------- js/iD/styleparser/RuleChain.js | 2 ++ js/iD/styleparser/RuleSet.js | 16 ++++++++-------- js/iD/styleparser/Style.js | 4 +--- js/iD/styleparser/StyleChooser.js | 4 +++- js/iD/styleparser/StyleList.js | 23 +++++++++++------------ 7 files changed, 34 insertions(+), 32 deletions(-) diff --git a/js/iD/styleparser/Condition.js b/js/iD/styleparser/Condition.js index c87b4cf82..85f08babf 100755 --- a/js/iD/styleparser/Condition.js +++ b/js/iD/styleparser/Condition.js @@ -10,11 +10,13 @@ declare("iD.styleparser.Condition", null, { params: [], // what to test against constructor:function(_type) { + // summary: A condition to evaluate. this.type =_type; this.params=Array.prototype.slice.call(arguments,1); }, test:function(tags) { + // summary: Run the condition against the supplied tags. var p=this.params; switch (this.type) { case 'eq': return (tags[p[0]]==p[1]); break; diff --git a/js/iD/styleparser/Rule.js b/js/iD/styleparser/Rule.js index f3413144e..4fc9a73e1 100755 --- a/js/iD/styleparser/Rule.js +++ b/js/iD/styleparser/Rule.js @@ -1,13 +1,9 @@ // iD/styleparser/Rule.js -/** A MapCSS selector. Contains a list of Conditions; the entity type to which the selector applies; - and the zoom levels at which it is true. way[waterway=river][boat=yes] would be parsed into one Rule. - The selectors and declaration together form a StyleChooser. */ - define(['dojo/_base/declare','dojo/_base/array'], function(declare,array){ // ---------------------------------------------------------------------- -// Rule base class +// Rule class declare("iD.styleparser.Rule", null, { @@ -18,18 +14,21 @@ declare("iD.styleparser.Rule", null, { subject: '', // entity type to which the Rule applies: 'way', 'node', 'relation', 'area' (closed way) or 'line' (unclosed way) constructor:function(_subject) { + // summary: A MapCSS selector. Contains a list of Conditions; the entity type to which the selector applies; + // and the zoom levels at which it is true. way[waterway=river][boat=yes] would be parsed into one Rule. + // The selectors and declaration together form a StyleChooser. this.subject=_subject; this.conditions=[]; }, addCondition:function(_condition) { + // summary: Add a condition to this rule. this.conditions.push(_condition); }, - - /** Evaluate the Rule on the given entity, tags and zoom level. - Return true if the Rule passes, false if the conditions aren't fulfilled. */ test:function(entity,tags,zoom) { + // summary: Evaluate the Rule on the given entity, tags and zoom level. + // returns: true if the Rule passes, false if the conditions aren't fulfilled. if (this.subject!='' && !entity.isType(this.subject)) { return false; } if (zoomthis.maxZoom) { return false; } diff --git a/js/iD/styleparser/RuleChain.js b/js/iD/styleparser/RuleChain.js index f83a0f4b0..f8130ff59 100755 --- a/js/iD/styleparser/RuleChain.js +++ b/js/iD/styleparser/RuleChain.js @@ -24,6 +24,7 @@ declare("iD.styleparser.RuleChain", null, { subpart: 'default', // subpart name, as in way[highway=primary]::centreline constructor:function() { + // summary: A descendant list of MapCSS selectors (Rules). this.rules=[]; }, @@ -60,6 +61,7 @@ declare("iD.styleparser.RuleChain", null, { // - if they succeed, and there's more in the chain, rerun this for each parent until success test:function(pos, entity, tags, zoom) { + // summary: Test a rule chain by running all the tests in reverse order. if (this.rules.length==0) { return false; } if (pos==-1) { pos=this.rules.length-1; } diff --git a/js/iD/styleparser/RuleSet.js b/js/iD/styleparser/RuleSet.js index 5ce178171..3df7917d4 100755 --- a/js/iD/styleparser/RuleSet.js +++ b/js/iD/styleparser/RuleSet.js @@ -5,7 +5,6 @@ define(['dojo/_base/xhr','dojo/_base/lang','dojo/_base/declare','dojo/_base/arra // ---------------------------------------------------------------------- // RuleSet base class // needs to cope with nested CSS files -// evals not done // doesn't do untagged nodes optimisation declare("iD.styleparser.RuleSet", null, { @@ -14,30 +13,31 @@ declare("iD.styleparser.RuleSet", null, { callback: null, constructor:function() { + // summary: An entire stylesheet in parsed form. this.choosers=[]; }, - registerCallback:function(_callback) { - this.callback=_callback; + registerCallback:function(callback) { + // summary: Set a callback function to be called when the CSS is loaded and parsed. + this.callback=callback; }, - // Find the styles for a given entity - getStyles:function(entity, tags, zoom) { + // summary: Find the styles for a given entity. var sl=new iD.styleparser.StyleList(); for (var i in this.choosers) { this.choosers[i].updateStyles(entity, tags, sl, zoom); } - return sl; + return sl; // iD.styleparser.StyleList }, - // Load from .mapcss file - loadFromCSS:function(url) { + // summary: Load a MapCSS file from a URL, then throw it at the parser when it's loaded. xhr.get({ url: url, load: lang.hitch(this, "parseCSS") }); }, parseCSS:function(css) { + // summary: Parse a CSS document into a set of StyleChoosers. var previous=0; // what was the previous CSS word? var sc=new iD.styleparser.StyleChooser(); // currently being assembled this.choosers=[]; diff --git a/js/iD/styleparser/Style.js b/js/iD/styleparser/Style.js index fd763048f..dfacfa26a 100755 --- a/js/iD/styleparser/Style.js +++ b/js/iD/styleparser/Style.js @@ -1,12 +1,9 @@ // iD/styleparser/Style.js -// Entity classes for iD define(['dojo/_base/declare','dojo/_base/array'], function(declare,array){ // ---------------------------------------------------------------------- // Style base class -// don't use deepCopy, use lang.clone instead -// evals not done yet // fillStyler not done for text yet declare("iD.styleparser.Style", null, { @@ -19,6 +16,7 @@ declare("iD.styleparser.Style", null, { evals: null, constructor: function(){ + // summary: Base class for a set of painting attributes, into which the CSS declaration is parsed. this.evals={}; }, diff --git a/js/iD/styleparser/StyleChooser.js b/js/iD/styleparser/StyleChooser.js index 82fb1f306..9571f607e 100755 --- a/js/iD/styleparser/StyleChooser.js +++ b/js/iD/styleparser/StyleChooser.js @@ -15,6 +15,8 @@ declare("iD.styleparser.StyleChooser", null, { stylepos:0, constructor:function() { + // summary: A combination of the selectors (ruleChains) and declaration (styles). + // For example, way[highway=footway] node[barrier=gate] { icon: gate.png; } is one StyleChooser. this.ruleChains=[new iD.styleparser.RuleChain()]; this.styles=[]; }, @@ -24,7 +26,7 @@ declare("iD.styleparser.StyleChooser", null, { }, newRuleChain:function() { - // starts a new ruleChain in this.ruleChains + // summary: Starts a new ruleChain in this.ruleChains. if (this.ruleChains[this.ruleChains.length-1].length()>0) { this.ruleChains.push(new iD.styleparser.RuleChain()); } diff --git a/js/iD/styleparser/StyleList.js b/js/iD/styleparser/StyleList.js index a85c4a19e..928a19f8b 100755 --- a/js/iD/styleparser/StyleList.js +++ b/js/iD/styleparser/StyleList.js @@ -4,13 +4,7 @@ define(['dojo/_base/declare'], function(declare){ // ---------------------------------------------------------------------- // StyleList class -// Not tested yet! -// A StyleList object is the full list of all styles applied to -// a drawn entity (i.e. node/way). -// Each array element applies to that sublayer (z-index). If there -// is no element, nothing is drawn on that sublayer. -// StyleLists are created by StyleChooser.getStyles. declare("iD.styleparser.StyleList", null, { @@ -23,6 +17,11 @@ declare("iD.styleparser.StyleList", null, { validAt:-1, // Zoom level this is valid at (or -1 at all levels - saves recomputing) constructor:function() { + // summary: A StyleList object is the full list of all styles applied to + // a drawn entity (i.e. node/way). Each array element applies to that + // sublayer (z-index). If there is no element, nothing is drawn on that sublayer. + // StyleLists are created by StyleChooser.getStyles. + this.shapeStyles={}; this.textStyles={}; this.pointStyles={}; @@ -30,39 +29,39 @@ declare("iD.styleparser.StyleList", null, { this.subparts=[]; }, - // Does this StyleList contain any styles? hasStyles:function() { + // summary: Does this StyleList contain any styles? return ( this.hasShapeStyles() || this.hasTextStyles() || this.hasPointStyles() || this.hasShieldStyles() ); }, - // Does this StyleList contain any styles with a fill? hasFills:function() { + // summary: Does this StyleList contain any styles with a fill? for (var s in this.shapeStyles) { if (!isNaN(this.shapeStyles(s).fill_color) || this.shapeStyles(s).fill_image) return true; } return false; }, - // Does this StyleList manually force an OSM layer? layerOverride:function() { + // summary: If this StyleList manually forces an OSM layer, return it, otherwise null. for (var s in this.shapeStyles) { if (!isNaN(this.shapeStyles[s].layer)) return this.shapeStyles[s].layer; } return NaN; }, - // Record that a subpart is used in this StyleList. addSubpart:function(s) { + // summary: Record that a subpart is used in this StyleList. if (this.subparts.indexOf(s)==-1) { this.subparts.push(s); } }, - // Is this StyleList valid at a given zoom? isValidAt:function(zoom) { + // summary: Is this StyleList valid at a given zoom? return (this.validAt==-1 || this.validAt==zoom); }, - // Summarise StyleList as String - for debugging toString:function() { + // summary: Summarise StyleList as String - for debugging var str=''; var k; for (k in this.shapeStyles ) { str+="- SS "+k+"="+this.shapeStyles[k]+"\n"; }