UI element documentation

js/iD/ui/DragAndDrop.js

@@ -23,12 +23,14 @@ declare("iD.ui.DragAndDrop", null, {
 	ICONPATH: 'icons/',
 	ITEMSPERROW: 5,
 
-	constructor:function(_divname,_map,_gridname) {
-		this.divname=_divname;
-		dom.byId(_divname).ondragover = lang.hitch(this,this.update);
-		dom.byId(_divname).ondrop = function(e) { e.preventDefault(); };	// required by Firefox
-		this.map=_map;
-		this.grid=dom.byId(_gridname);
+	constructor:function(divname, map, gridname) {
+		// summary:		Singleton-like class for POI drag and drop. Loads a config file (draganddrop.json)
+		//				on initialisation, then populates the drop-down palette with it.
+		this.divname=divname;
+		dom.byId(divname).ondragover = lang.hitch(this,this.update);
+		dom.byId(divname).ondrop = function(e) { e.preventDefault(); };	// required by Firefox
+		this.map=map;
+		this.grid=dom.byId(gridname);
 
 		// Load drag and drop config file
 		dojo.xhrGet({
@@ -41,6 +43,7 @@ declare("iD.ui.DragAndDrop", null, {
 	},
 
 	drawGrid:function(obj) {
+		// summary:		Draw the grid of icons based on the JSON-derived object loaded.
 		var row;
 		for (var i=0; i<obj.length; i++) {
 			var item=obj[i];
@@ -62,14 +65,16 @@ declare("iD.ui.DragAndDrop", null, {
 	},
 
 	update:function(event) {
+		// summary:		Handler for dragging over the map; tells the browser that it's droppable here.
 		this.dragevent=event;
 		event.preventDefault();
 	},
 
 	end:function(event) {
+		// summary:		Create a new POI from the dropped icon.
 		var lon=this.map.coord2lon(this.map.mouseX(this.dragevent));
 		var lat=this.map.coord2lat(this.map.mouseY(this.dragevent));
-		var tags=this.parseKeyValues(event.target.getAttribute('alt'));
+		var tags=this._parseKeyValues(event.target.getAttribute('alt'));
 
 		var action=new iD.actions.CreatePOIAction(this.map.conn,tags,lat,lon);
 		this.map.controller.undoStack.addAction(action);
@@ -80,7 +85,8 @@ declare("iD.ui.DragAndDrop", null, {
 		this.map.controller.setState(new iD.controller.edit.SelectedPOINode(node));
 	},
 
-	parseKeyValues:function(string) {
+	_parseKeyValues:function(string) {
+		// summary:		Turn a string of format k1=v1;k2=v2;... into a hash.
 		var pairs=string.split(';');
 		var tags={};
 		for (var i in pairs) {

js/iD/ui/StepPane.js

@@ -9,12 +9,6 @@ define(['dojo/_base/declare','dojo/_base/lang'], function(declare,lang){
 // ----------------------------------------------------------------------
 // StepPane class
 
-// ******
-// This is a bit messy at present - it shouldn't take stepsname or similar, it should just
-// create the pane programmatically.
-// ******
-// We should also be able to set the title of the pane.
-
 declare("iD.ui.StepPane", null, {
 
 	divname: null,
@@ -23,27 +17,45 @@ declare("iD.ui.StepPane", null, {
 	order: null,
 	
 	constructor:function(_divname,_stepsdivname) {
+		// summary:		Populates and creates the 'Step by step' how-to panel.
+		//				This is a bit messy at present - it shouldn't take stepsname or similar, it should just
+ 		//				create the pane programmatically. We should also be able to set the title of the pane.
 		this.divname=_divname;
 		this.stepsname=_stepsdivname;
 		this.order=[];
 	},
 
-	// Getters for the <div> containing the steps, and its individual nodes
-
-	stepsDiv:function() { return document.getElementById(this.stepsname); },
-	stepsNodes:function() { return this.stepsDiv().childNodes; },
+	stepsDiv:function() {
+		// summary:		Getter for the <div> containing the steps.
+		return document.getElementById(this.stepsname);
+	},
+	stepsNodes:function() { 
+		// summary:		Getter for the nodes of the <div> containing the steps.
+		return this.stepsDiv().childNodes;
+	},
 
+	// ----------------
 	// Add/remove steps
 
 	addStep:function(name,text) {
+		// summary:		Add a step to the end of the list.
+		// name: String	A reference to this step (for example, 'start').
+		// text: String	The text of the step.
 		this.order.push(name);
 		this.stepsDiv().appendChild(document.createElement('li')).innerHTML=text;
 	},
 	insertStep:function(pos,name,text) {
+		// summary:		Insert a step at a position within the list.
+		// pos: Number	The index at which to insert the step.
+		// name: String	A reference to this step (for example, 'start').
+		// text: String	The text of the step.
 		this.order.splice(pos,0,name);
 		this.stepsNodes()[pos+1].insertBefore(document.createElement('li')).innerHTML=text;
 	},
 	setSteps:function(steps,order) {
+		// summary:		Set the entire list of steps.
+		// steps: Object	A hash of each step, keyed by reference name. For example: { start: 'Click to begin', ... }
+		// order: String	An array of the step names, in the desired order. For example: ['start','add','finish']
 		this.clear();
 		for (var i=0; i<order.length; i++) {
 			this.addStep(order[i], steps[order[i]]);
@@ -51,15 +63,18 @@ declare("iD.ui.StepPane", null, {
 		return this;
 	},
 	clear:function() {
+		// summary:		Remove all steps.
 		for (var i=this.stepsNodes().length-1; i>=1; i--) {
 			this.stepsDiv().removeChild(this.stepsNodes()[i]);
 		}
 		this.order=[];
 	},
 
+	// ---------------------------
 	// Change the highlighted step
 
 	highlight:function(stepname) {
+		// summary:		Highlight the step with the specified name, and dim all others.
 		this.show();
 		this.currentStep=stepname;
 		for (var i=1; i<this.stepsNodes().length; i++) {
@@ -67,12 +82,15 @@ declare("iD.ui.StepPane", null, {
 		}
 	},
 
+	// ----------------
 	// Show/hide window
 	
 	show:function() {
+		// summary:		Show the window.
 		dijit.byId(this.divname).show();
 	},
 	hide:function() {
+		// summary:		Hide the window.
 		dijit.byId(this.divname).hide();
 	},