From eccbf4c639c693bccc4f154236094163be0878b8 Mon Sep 17 00:00:00 2001
From: Richard Fairhurst <richard@systemeD.net>
Date: Thu, 12 Jul 2012 16:51:57 +0100
Subject: [PATCH] Start Controller documentation

---
 js/iD/Controller.js                 |  4 ++++
 js/iD/controller/ControllerState.js | 16 ++++++++++++++--
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/js/iD/Controller.js b/js/iD/Controller.js
index 16436b840..0207b4145 100755
--- a/js/iD/Controller.js
+++ b/js/iD/Controller.js
@@ -12,15 +12,18 @@ declare("iD.Controller", null, {
 	undoStack: null,		// main undoStack
 	
 	constructor:function(_map) {
+		// summary:		The Controller marshalls ControllerStates and passes events to them.
 		this.map=_map;
 		this.undoStack=new iD.actions.UndoStack();
 	},
 
 	setStepper:function(_stepper) {
+		// summary:		Set reference for the singleton-like class for the step-by-step instruction panel.
 		this.stepper=_stepper;
 	},
 	
 	setState:function(newState) {
+		// summary:		Enter a new ControllerState, firing exitState on the old one, and enterState on the new one.
 		if (newState==this.state) { return; }
 		if (this.state) { 
 			this.state.exitState(newState);
@@ -33,6 +36,7 @@ declare("iD.Controller", null, {
 	},
 	
 	entityMouseEvent:function(event,entityUI) {
+		// summary:		Pass a MouseEvent on an EntityUI (e.g. clicking a way) to the current ControllerState.
 		if (!this.state) { return; }
 		var newState=this.state.processMouseEvent(event,entityUI);
 		this.setState(newState);
diff --git a/js/iD/controller/ControllerState.js b/js/iD/controller/ControllerState.js
index 842ba4b82..764d11328 100755
--- a/js/iD/controller/ControllerState.js
+++ b/js/iD/controller/ControllerState.js
@@ -9,36 +9,48 @@ declare("iD.controller.ControllerState", null, {
 	controller: null,		// parent Controller
 	
 	constructor:function() {
+		// summary:		Base class for ControllerStates.
 	},
 
 	setController:function(_controller) {
+		// summary:		Set a reference to the parent Controller.
 		this.controller=_controller;
 	},
 	
 	processMouseEvent:function(event,entityUI) {
+		// summary:		Process mouse events. Most of the UI handling goes on in here.
+		// returns: iD.controller.ControllerState	The ControllerState to move to as a result of the user's actions (or just 'this' for no change).
 	},
 	
 	enterState:function() {
+		// summary:		Do any work required for entering the ControllerState, such as highlighting the selected entity.
 	},
 
 	exitState:function(newState) {
+		// summary:		Do any work required to leave the ControllerState clearly, such as unhighlighting the selected entity.
 	},
 
 	stateName:function() {
+		// summary:		Return the name of this state as a string, e.g. 'edit.NoSelection'.
+		// return:		String
 		return this.stateNameAsArray.join('.');
 	},
 	
 	stateNameAsArray:function() {
+		// summary:		Return the name of this state as an array, e.g. ['edit','NoSelection'].
+		// return:		Array
 		return this.__proto__.declaredClass.split('.').slice(2);
 	},
 	
 	getConnection:function() {
+		// summary: 	Shorthand to return the Connection associated with this Controller (via its Map object).
+		// return:		iD.Connection
 		return this.controller.map.conn;
 	},
 	
 	undoAdder:function() {
-		/* This is a convenient shorthand for adding an action to the global undo stack,
-		   setting the scope correctly. */
+		// summary:		Shorthand for adding an action to the global undo stack, setting the scope correctly.
+		// return:		Function
 		return lang.hitch(this.controller.undoStack, this.controller.undoStack.addAction);
 	}