Merge pull request #20 from Databean/documentation

Document ALL the things!

Author: PickledMonkey

include/City.h

@@ -3,6 +3,9 @@
 
 #include "CornerPiece.h"
 
+/**
+ * Upgraded from a Settlement. Exists on the board, and receives two resources from adjacent tiles when their number is rolled.
+ */
 class City : public CornerPiece {
 private:
 

include/CornerPiece.h

@@ -4,6 +4,10 @@
 #include "GamePiece.h"
 #include "Player.h"
 
+/**
+ * A piece that exists on one of the corners of a resource hexagon. Currently is either a Settlement or City, both of which
+ * receive resources from adjacent resource tiles.
+ */
 class CornerPiece : public GamePiece {
 private:
 	Player& owner;

include/Deck.h

@@ -13,6 +13,10 @@
 #include <algorithm>
 #include "DevelopmentCard.h"
 
+/**
+ * A collection of Settlers of Catan cards, initialized with the cards available in the standard game
+ * in the original amounts.
+ */
 class Deck {
 
 private:

include/DevelopmentCard.h

@@ -20,7 +20,9 @@
 enum DevCardType { KNIGHT, VICTORYPOINT, YEAROFPLENTY, MONOPOLY, ROADBUILDING };
 
 
-
+/**
+ * A card which can be held in a player's hand and be used to perform an action.
+ */
 class DevelopmentCard {
 
 private:
@@ -38,8 +40,9 @@ class DevelopmentCard {
 	virtual bool operator==(const DevelopmentCard&);
 };
 
-
-
+/**
+ * A development card used to move the robber and take a resource from another player.
+ */
 class KnightCard : public DevelopmentCard {
 private:
 
@@ -52,8 +55,9 @@ class KnightCard : public DevelopmentCard {
 
 };
 
-
-
+/**
+ * A development card that gives a permanent victory point on usage.
+ */
 class VictoryPointCard : public DevelopmentCard {
 public:
     VictoryPointCard(Player* player);
@@ -64,7 +68,9 @@ class VictoryPointCard : public DevelopmentCard {
 
 };
 
-
+/**
+ * A development card used to retrieve two resources of any type from the bank.
+ */
 class YearOfPlentyCard : public DevelopmentCard {
 public:
     YearOfPlentyCard(Player* player);
@@ -75,9 +81,9 @@ class YearOfPlentyCard : public DevelopmentCard {
 
 };
 
-
-
-
+/**
+ * A development card used to take all resources of a particular type from all players.
+ */
 class MonopolyCard : public DevelopmentCard {
 public:
     MonopolyCard(Player* player);
@@ -88,8 +94,9 @@ class MonopolyCard : public DevelopmentCard {
 
 };
 
-
-
+/**
+ * A development card used to build two roads at no cost.
+ */
 class RoadBuildingCard : public DevelopmentCard {
 private:
 

include/GameBoard.h

@@ -20,6 +20,9 @@
 
 class GameVisitor;
 
+/**
+ * A game of Settlers of Catan, including resource tiles, settlements, cities, roads, and players.
+ */
 class GameBoard {
 private:
 	std::map<Coordinate, std::unique_ptr<CornerPiece>> corners;

include/GameController.h

@@ -7,6 +7,10 @@ class GameBoard;
 class ClickCoordinateEvent;
 class GameView;
 
+/**
+ * Takes interpreted Catan events from the View and calls the appropriate functions on the model to changee the state
+ * in response.
+ */
 class GameController {
 private:
 	GameBoard& model;

include/GamePiece.h

@@ -10,6 +10,10 @@ enum resourceType { WHEAT, SHEEP, STONE, BRICK, WOOD, DESERT };
 
 class GameBoard;
 
+/**
+ * Something that occupies a position in triangular coordinates on the board. Currently is either a
+ * CornerPiece(Settlement or City) or a ResourceTile.
+ */
 class GamePiece {
 private:
 	GameBoard& board;
@@ -33,6 +37,10 @@ class GamePiece {
 
 };
 
+/**
+ * One of the hexagons that has a particular resource and a dice number on the board. When the dice
+ * roll its number, resources are paid out to adjacent cities.
+ */
 class ResourceTile : public GamePiece {
 public:
 	ResourceTile(GameBoard& board);

include/GameView.h

@@ -16,6 +16,10 @@ class GameController;
 class ViewElement;
 class GameView;
 
+/**
+ * An element that is drawn on screen and can receive inputs from the user. These all occupy a rectangular area on screen
+ * and can choose to handle clicks from the user that are inside their area.
+ */
 class ViewElement {
 private:
 	std::pair<ScreenCoordinate, ScreenCoordinate> rect;
@@ -34,6 +38,9 @@ class ViewElement {
 	virtual void render() = 0;
 };
 
+/**
+ * The class in charge of drawing the view to the screen, using OpenGL calls.
+ */
 class GameView {
 private:
 	GameBoard& model;
@@ -52,6 +59,9 @@ class GameView {
 	void addElement(std::unique_ptr<ViewElement>);
 };
 
+/**
+ * A visitor of the GameBoard hierarchy that draws the entire model.
+ */
 class DrawingGameVisitor : public GameVisitor {
 private:
 	GameView& view;
@@ -71,6 +81,9 @@ class DrawingGameVisitor : public GameVisitor {
 	virtual void visit(DevelopmentCard&);
 };
 
+/**
+ * A view element that is invisible and calls a callback function when it is clicked.
+ */
 template<class Fn>
 class ViewButton : public ViewElement {
 private:
@@ -89,11 +102,21 @@ class ViewButton : public ViewElement {
 	virtual void render() {}
 };
 
+/**
+ * Constructs a ViewButton using the same parameters as the ViewButton. Exists because template inference exists only
+ * for functions, not classes.
+ * @param fn The callback function to be called with the ScreenCoordinate clicked and returning a boolean on if it was handled.
+ * @param rect The location on screen that the invisible button receives clicks from.
+ * @return An owning unique pointer to the constructed view button.
+ */
 template<class Fn>
 std::unique_ptr<ViewElement> makeViewButton(Fn fn, std::pair<ScreenCoordinate, ScreenCoordinate> rect) {
 	return std::unique_ptr<ViewElement>(new ViewButton<Fn>(fn, rect));
 }
 
+/**
+ * A view element drawn as a solid color that has a callback function that is called when it is clicked.
+ */
 template<class Fn>
 class ViewButtonColor : public ViewButton<Fn> {
 private:
@@ -119,6 +142,14 @@ class ViewButtonColor : public ViewButton<Fn> {
 	}
 };
 
+/**
+ * Constructs a ViewButtonColor using the same parameters as the ViewButtonColor. Exists because template inference exists only
+ * for functions, not classes.
+ * @param fn The callback function to be called with the ScreenCoordinate clicked and returning a boolean on if it was handled.
+ * @param rect The location on screen to draw to and receive clicks from.
+ * @param color The color to draw the button. RGB floats from 0 to 1 for intensity.
+ * @return An owning unique pointer to the constructed view button.
+ */
 template<class Fn>
 std::unique_ptr<ViewElement> makeViewButtonColor(Fn fn, std::pair<ScreenCoordinate, ScreenCoordinate> rect, std::tuple<float, float, float> color) {
 	return std::unique_ptr<ViewElement>(new ViewButtonColor<Fn>(fn, rect, color));

include/GameVisitor.h

@@ -9,6 +9,9 @@ class City;
 class Player;
 class DevelopmentCard;
 
+/**
+ * A class to be extended with callbacks to handle the different classes in the model. 
+ */
 class GameVisitor {
 private:
 	//Block copy constructor and assignment operator

include/Player.h

@@ -30,7 +30,10 @@ class Deck;
 class GameBoard;
 
 
-
+/**
+ * One of the players interacting with the Settlers of Catan game. Contains her name, victory points,
+ * development cards, and resources.
+ */
 class Player {
 private:
     std::string name;