some helpful comments / documentation

src/Button.as

@@ -1,7 +1,7 @@
 package  
 {
 	/**
-	 * ...
+	 * Button widget; when clicked, calls a function.
 	 * @author jjp
 	 */
 	public class Button extends EntitySidebarImg

src/Drag.as

@@ -3,7 +3,8 @@ package
 	import flash.geom.Point;
 	import net.flashpunk.utils.Input;
 	/**
-	 * ...
+	 * Keeps track of mouse dragging.  Has a global scheme that ensures only one thing is being dragged at a time.
+	 * Use Drag.Claim instead of new Drag().
 	 * @author jjp
 	 */
 	public class Drag

src/EntitySidebar.as

@@ -28,5 +28,4 @@ package
 		public function OnClick(): void { }
 		public function Fade(pct:Number):void { }
 	}
-
 }

src/FileWatcher.as

@@ -5,7 +5,8 @@ package
 	import flash.events.EventDispatcher;
 	import flash.filesystem.File;
 	/**
-	 * ...
+	 * Watches an image file for changes, reloads it if it sees any.  Uses a global reference-counting scheme to keep track of
+	 * which objects care about a particular file.  Use "FileWatcher.Get", not "new Filewatcher".
 	 * @author jjp
 	 */
 	public class FileWatcher

src/Imgdir.as

@@ -11,7 +11,8 @@ package
 	import flash.filesystem.File;
 	import flash.net.URLRequest;
 	/**
-	 * ...
+	 * Monitors a directory for new image files placed in it, and sends out AS3 events containing their BitmapData when it finds some.
+	 * Also contians a static helper function for asynchronously loading image files.
 	 * @author jjp
 	 */
 	public class Imgdir extends EventDispatcher

src/Sidebar.as

@@ -11,7 +11,9 @@ package
 	import net.flashpunk.utils.Ease;
 	
 	/**
-	 * ...
+	 * A sidebar contains a vertically-stacked list of EntitySidebars, can be shuffled on and off the screen, and can optionally be scrolled.
+	 * A sidebar claims two layers; the layer passed in to the sidebar constructor is where the EntitySidebars live, and layer + 1 is where
+	 * the sidebar entity lives.  NO OTHER ENTITIES SHOULD BE ON THESE LAYERS.
 	 * @author jjp
 	 */
 	public class Sidebar extends Entity

src/WorldStage.as

@@ -16,6 +16,13 @@
 // bar/baz/               -- urfd
 // bar/                   -- urpd
 
+// seriously I promise after fifteen minutes of working with this nomenclature it becomes second nature.
+
+// dg -- function pointer
+// rg -- list
+// mpfoo_bar -- a dictionary with foos for keys and bars for values
+// bmp -- a FlashPunk "source" like BitmapData or a Class of an embedded image
+
 package  
 {
 	import flash.display.BitmapData;
@@ -110,15 +117,8 @@ package
 		{
 			return new Point((pointReal.x - pointView.x) * zoom, (pointReal.y - pointView.y) * zoom);
 		}
-		private function OnNewImg(ev: EvNewImg) : void
+		
-		{
+		// path management helpers
-			var entity: Entity;
-			if (ev.bmp === null)
-				entity = new Folder(SidebarFind(LAYER_SIDEBAR), ev.urp);
-			else
-				entity = new Factory(SidebarFind(LAYER_SIDEBAR), ev.urp, ev.bmp);
-		}
-				
 		public function UabFromUrf(urf:String): String
 		{
 			return uabd + urf;
@@ -131,6 +131,8 @@ package
 		{
 			return rgurpd.join("") + "/";
 		}
+		
+		// left sidebar (folders and objects) management
 		public function Chdir(urpd: String): void
 		{
 			if (alarmImgdir !== null)
@@ -160,6 +162,16 @@ package
 			if (rgurpd.length > 0)
 				OnNewImg(new EvNewImg(Imgdir.LOADED, "../", null));
 		}
+		private function OnNewImg(ev: EvNewImg) : void
+		{
+			var entity: Entity;
+			if (ev.bmp === null)
+				entity = new Folder(SidebarFind(LAYER_SIDEBAR), ev.urp);
+			else
+				entity = new Factory(SidebarFind(LAYER_SIDEBAR), ev.urp, ev.bmp);
+		}
+
+		// sidebar management
 		private function SidebarFind(layer: int):Sidebar
 		{
 			for each (var sidebar:Sidebar in rgsidebar)
@@ -179,6 +191,7 @@ package
 					return true;
 				}, this);			
 		}
+		// add a sidebar to the world, replacing an existing sidebar on the same layer (if any).
 		private function AddSidebar(sidebar: Sidebar):Sidebar
 		{
 			RemoveSidebar(sidebar.LayerEntities());
@@ -191,9 +204,22 @@ package
 			for each (var sidebar: Sidebar in rgsidebar)
 				sidebar.Toggle();
 		}
+		
+		// top-level UI policy (token selection, sidebar clicking & scrolling, stage zooming & dragging, UI hiding & showing)
+		
+		// yes this is messy but at our current level of UI complexity it should be clear how all of the policies interact
+		// it would be "better" in some abstract sense if the world simply dispatched events to widget objects, but that's
+		// not how FlashPunk works so that's not how we do it either
+		
+		// leave this function cleaner than you found it
+		
+		// if it turns out we need more than one of a particular kind of widget please create a class and design a protocol for handing
+		// off control to that thing from this (like tokSelected)
+		
+		// I've passed the stage in my programming career where I would happily spend a few months designing a generic GUI library in
+		// response to this problem and consequently forget about my original goal; there are a few other projects doing that for me
 		override public function update():void 
 		{
-			var dyFactory:int = 0;
 			if (Input.mouseUp && dragView !== null)
 			{
 				trace("drag done");
@@ -203,9 +229,9 @@ package
 
 			if (Input.mousePressed)
 			{
-				if (Input.check(Key.SHIFT))
+				if (Input.check(Key.SHIFT)) // shift-click -- begin view dragging
 					dragView = Drag.Claim();
-				else
+				else 						// click -- select a token
 				{
 					var rgtok: Array = [];
 					getLayer(LAYER_TOKENS, rgtok);
@@ -223,15 +249,18 @@ package
 					trace("clicked on " + tokSelected);
 				}
 			}
-			if (dragView !== null)
+			if (dragView !== null) // shift-drag -- do view dragging
 			{
 				pointView = pointView.subtract(dragView.Delta(zoom));
 				dragView.Update();
 			}
+			
 			if (Input.pressed(Key.TAB))
 				ToggleUI();
+				
 			if (Input.mouseWheel)
 			{
+				// scroll a sidebar if overtop of a scrollable one
 				var fSidebarScrolled:Boolean = false;
 				for each (var sidebar: Sidebar in rgsidebar)
 				{
@@ -242,7 +271,7 @@ package
 						break;
 					}
 				}
-				if (!fSidebarScrolled)
+				if (!fSidebarScrolled) // otherwise adjust zoom
 				{
 					var zoomNew: Number = zoom + (Input.mouseWheelDelta / 100);
 					if (zoomNew <= 0)
@@ -258,6 +287,7 @@ package
 			super.update();
 		}
 		
+		// message management
 		public function ShowMsg(stMsg: String):void
 		{
 			rgmsg.push(stMsg);
@@ -285,12 +315,16 @@ package
 				alarmMsg = Alarm(addTween(new Alarm(2, function():void { sidebarMsg.Toggle(ShowNextMsg); }, Tween.ONESHOT), true));
 			}
 		}
+		
+		// right sidebar commands
 		private function ResetZoom(): void
 		{
 			var pointMiddle: Point = new Point(FP.halfWidth, FP.halfHeight);
 			pointView = PointRealFromScreen(pointMiddle).subtract(pointMiddle);
 			zoom = 1;
 		}
+		
+		// persistence (save/load/XML generation)
 		public function Save(): void
 		{
 			var stream: FileStream = new FileStream();