Add some comments

src/include/level.h

@@ -21,11 +21,15 @@ class Level {
 		void generate(PlayerChar);
 		bool contains(Coord);
 		static Coord getSize() { return Coord(X_SIZE, Y_SIZE); };
+		// Add a mob to the level's collection
 		void registerMob(Mob*);
 		std::vector<Mob*> getMobs();
 		Mob* popTurnClock();
+		// move a mob back in the turn clock equal to the amount specified
 		void pushMob(Mob*, int);
 	private:
+		// Store mobs with a notation for how many
+		// 'ticks' they are from being the current actor
 		struct ClockItem {
 			ClockItem(Mob* mob, int delay) 
 				: mob(mob)

src/include/uistate.h

@@ -4,7 +4,10 @@
 class UIState {
 	public:
 		UIState();
+		// Render the current UI
 		virtual void draw(TCODConsole*);
+		// Do whatever is needed in response to keypresses
+		// then return state to transition to (can be self)
 		virtual UIState* handleInput(TCOD_key_t);
 		virtual ~UIState();
 };

src/mainmenu.cpp

@@ -17,15 +17,18 @@ void MainMenu::draw(TCODConsole* con) {
 
 UIState* MainMenu::handleInput(TCOD_key_t key) {
 	if (!key.pressed) return this;
+	// Chop off a character in response to backspaces
 	if (key.vk == TCODK_BACKSPACE) {
 		if (!nameBuffer.empty()) {
 			nameBuffer.resize(nameBuffer.size()-1);
 		}
+	// If enter we generate the first level and start the game
 	} else if (key.vk == TCODK_ENTER) {
 		Level* level = new Level(0);
 		PlayerChar* player = new PlayerChar(nameBuffer, Coord(10, 10));
 		level->registerMob(player);
 		level->generate(*player);
+		// Place the player in the upper-left clear spot
 		for (int x=0; x < level->getSize()[0]; x++) {
 			for (int y=0; y < level->getSize()[1]; y++) {
 				if ((*level)[Coord(x,y)].isPassable() == Terrain::Passable) {
@@ -37,6 +40,7 @@ UIState* MainMenu::handleInput(TCOD_key_t key) {
 		L_exit:
 		return new PlayState(player, level);
 	} else if (key.c) {
+		// Append to name if its a valid name character
 		if (VALID_NAME.find(key.c) != std::string::npos) {
 			nameBuffer = nameBuffer + key.c;
 		}

src/mastercontroller.cpp

@@ -17,16 +17,22 @@ void MasterController::run() {
     //Init console
 	Coord lSize = Level::getSize();
     TCODConsole::initRoot(lSize[0], lSize[1] + spacer, "Rogue Reborn", false);
+	// floatCon is our 'false root' so we don't have to work with the root
+	// console -> more flexibility and maintainability
     TCODConsole* floatCon = new TCODConsole(lSize[0], lSize[1] + spacer);
+	// Limits number of flushes/second so we don't consum 100% cpu
 	TCODSystem::setFps(FPS_LIMIT);
 	//Game loop
     while (!TCODConsole::isWindowClosed()) {	
         TCOD_key_t key;
 		auto temp = currState;
-		currState = currState->handleInput(key);	
+		currState = currState->handleInput(key);
+		// Transition to the next state, cleaning up behind
+		// us if necessary.
 		if (temp != currState) {
 			delete temp;
 		}
+		// Terminate the game on NULL return
 		if (currState == NULL) {
 			break;
 		}
@@ -34,7 +40,7 @@ void MasterController::run() {
 		floatCon->clear();
 		currState->draw(floatCon);
 		TCODConsole::blit(floatCon,0,0,lSize[0],lSize[1]+spacer,TCODConsole::root,0,0);
-		TCODConsole::flush();	
+		TCODConsole::flush();
 	}
 	delete floatCon;
 }

src/playstate.cpp

@@ -7,15 +7,26 @@
 #include <iostream>
 #include <string>
 
+/* The game can prompt the user for response.
+ * This is blocking, but the level view remains.
+ * Acts as a sub-uistate internal to playstate,
+ * so we don't have to duplicate rendering stuff.
+ */
 class Prompt {
-
 	public:
 		Prompt(PlayerChar* player, Level* level)
 			: player(player)
 			, level(level)
 		{}
 		virtual ~Prompt() {};
+		/* Q: Why do prompts need arbitrary rendering capabilities
+		 * instead of just drawing a string?
+		 * A: Sometimes the prompt needs to highlight letters to
+		 * indicate the keyboard shortcuts
+		 */
 		virtual void showText(TCODConsole* con, int x, int y) {};
+		// Transitions indicate where the owning PlayState
+		// should transfer control next (could be prompt or uistate)
 		struct Transition {
 			Transition(Prompt* p, UIState* s)
 				: nextPrompt(p)
@@ -30,6 +41,10 @@ class Prompt {
 		Level* level;
 };
 
+/* Player can press shift+q to enter a game-quit
+ * prompt, which will ask for confirmation, then
+ * transition to RIP/score screen.
+ */
 class QuitPrompt : public Prompt {
 	public:
 		QuitPrompt(PlayerChar* player, Level* level)
@@ -58,6 +73,7 @@ PlayState::PlayState(PlayerChar* play, Level* lvl)
 {}
 
 void PlayState::draw(TCODConsole* con) {
+	// Draw terrain
 	for (auto x=0; x < level->getSize()[0]; x++) {
 		for (auto y=0; y < level->getSize()[1]; y++) {
 			auto mapPos = Coord(x, y);
@@ -65,9 +81,11 @@ void PlayState::draw(TCODConsole* con) {
 			con->putChar(scrPos[0], scrPos[1], (*level)[mapPos].getSymbol());
 		}
 	}
+	// Display the prompt
 	if (prompt != NULL) {
 		prompt->showText(con, 0, 0);
 	}
+	// Display the mobs
 	for (Mob* mob : level->getMobs()) {
 		auto scrPos = mob->getLocation().asScreen();
 		con->putChar(scrPos[0], scrPos[1], mob->getSymbol());
@@ -87,6 +105,7 @@ UIState* PlayState::handleInput(TCOD_key_t key) {
 		}
 		return this;
 	}
+	// Perform AI turns until it's the player's go
 	while (true) {
 		auto nextUp = level->popTurnClock();
 		if (nextUp == player) {