# HG changeset patch
# User terom
# Date 1228740397 0
# Node ID 7540b08595796477f434c2ef1658504ce7550de8
# Parent  e0e4dfc3e52856f25c2b1f2c948fc28384d75544
start adding some documentation, most core classes (outside of Network) are now doxygen-enabled

diff -r e0e4dfc3e528 -r 7540b0859579 doc/doxygen/doxygen.cfg
--- a/doc/doxygen/doxygen.cfg	Mon Dec 08 12:02:20 2008 +0000
+++ b/doc/doxygen/doxygen.cfg	Mon Dec 08 12:46:37 2008 +0000
@@ -2,5 +2,5 @@
 OUTPUT_DIRECTORY = html
 WARNINGS = YES
 INPUT = ../../src
-FILE_PATTERNS = *.cc *.hh
+FILE_PATTERNS = *.hh */*.hh
 PERL_PATH = /usr/bi/perl
diff -r e0e4dfc3e528 -r 7540b0859579 src/Config.hh
--- a/src/Config.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/Config.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -9,7 +9,9 @@
 // This is a temporary way to declare different constants. Maybe we
 // should do somekind of resource manager? Do we have time?
 
-// Mathematical constants
+/**
+ * The value of pi used in physics/graphics calculations
+ */
 const float KG_PI = 3.14159265;
 
 // Physics simulation
@@ -21,7 +23,9 @@
 // Simulation
 const uint16_t PHYSICS_TICK_MS = 10;
 
-// Constants affecting physics
+/**
+ * The force of gravity on objects, exerted on the Y axis
+ */
 const float MAP_GRAVITY = 1500.0;
 
 // Player properties
diff -r e0e4dfc3e528 -r 7540b0859579 src/Engine.hh
--- a/src/Engine.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/Engine.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -11,6 +11,9 @@
 
 #include "Logger.hh"
 
+/**
+ * This is the core class that glues all the other components together and runs the main loop
+ */
 class Engine {
     private:
         // game state
diff -r e0e4dfc3e528 -r 7540b0859579 src/Graphics.hh
--- a/src/Graphics.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/Graphics.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -13,6 +13,10 @@
 #include <ClanLib/gl.h>
 #include <ClanLib/display.h>
 
+/**
+ * This handles drawing the GameState with an appropriate camera view each frame, loading fonts, and currently,
+ * handling the input from Input to GameState.
+ */
 class Graphics : public CL_DisplayWindow {
 private:
     Engine &engine;
diff -r e0e4dfc3e528 -r 7540b0859579 src/Input.hh
--- a/src/Input.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/Input.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -5,8 +5,13 @@
 #include <ClanLib/Display/input_device.h>
 #include <ClanLib/Display/keys.h>
 
-// const uint16_t INPUT_INTERVAL_MS = 20;
+// const TimeMS INPUT_INTERVAL_MS = 20;
 
+/**
+ * The bits used in the PlayerInput bitmask, each represents a separate action handled by LocalPlayer::handleInput.
+ *
+ * @see LocalPlayer::handleInput
+ */
 enum PlayerInputBit {
     INPUT_NONE          = 0x0000,
 
@@ -27,17 +32,37 @@
     INPUT_ROPE_DOWN     = 0x1000,
 };
 
+/**
+ * The bits used in the GuiInput bitmask, each represents something handled locally by Graphics.
+ */
 enum GuiInputBit {
     GUI_INPUT_QUIT              = 0x0001,
     GUI_INPUT_DISPLAY_WEAPON    = 0x0002,
     GUI_INPUT_DEBUG_PLAYER      = 0x0004,
 };
 
+/**
+ * Bitmask of PlayerInputBits
+ *
+ * @see PlayerInputBit
+ */
 typedef uint16_t PlayerInput;
+
+/**
+ * Bitmask for GuiInputBits
+ *
+ * @see GuiInputBit
+ */
 typedef uint16_t GuiInput;
 
+/**
+ * Keymap definition used in Input.cc
+ */
 template <typename BitEnumType> struct InputKeymapEntry;
 
+/**
+ * Handles reading input from a keyboard and mapping it to PlayerInput/GuiInput bitmasks
+ */
 class Input {
     protected:
         CL_InputDevice &keyboard;
diff -r e0e4dfc3e528 -r 7540b0859579 src/Logger.hh
--- a/src/Logger.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/Logger.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -5,6 +5,11 @@
 
 #include <iostream>
 
+/**
+ * Message severity, WARN and above should go to stderr, INFO and DEBUG to stdout
+ *
+ * @see Engine::log
+ */
 enum LogLevel {
     FATAL,
     ERROR,
@@ -13,6 +18,11 @@
     DEBUG,
 };
 
+/**
+ * Utility class used for logging, use Engine::log to construct these
+ *
+ * @see Engine::log
+ */
 class Logger {
     private:
         std::ostream &stream;
diff -r e0e4dfc3e528 -r 7540b0859579 src/Player.hh
--- a/src/Player.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/Player.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -13,6 +13,10 @@
 #include "GraphicsPointer.hh"
 #include <vector>
 
+/**
+ * A Player is a PhysicsObject that represents a player - a remote client on the server, a local singleplayer player, a
+ * local network-client player, a remote network-client player, etc.
+ */
 class Player : public PhysicsObject {
     friend class Rope;
 
@@ -99,6 +103,12 @@
     virtual void draw (Graphics *g, PixelCoordinate camera);
 };
 
+/**
+ * A LocalPlayer is a Player that we handle input for - so this is our own player on the client/singleplayer, or all
+ * the remote clients on a server - the name is a bit misleading.
+ *
+ * This inherits virtually from Player so that subclasses can also define custom behaviour for the base Player class.
+ */
 class LocalPlayer : public virtual Player {
 private:
     /*
@@ -125,6 +135,12 @@
     virtual void draw (Graphics *g, bool displayWeapon, PixelCoordinate camera);
 };
 
+/**
+ * A RemotePlayer is a Player that we don't handle input for - they are a remote client connected to a remote server.
+ *
+ * This inherits virtually from Player so that subclasses can also define custom behaviour for the base Player class.
+ */
+
 class RemotePlayer : public virtual Player {
 protected:
 };
diff -r e0e4dfc3e528 -r 7540b0859579 src/Projectile.hh
--- a/src/Projectile.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/Projectile.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -8,6 +8,11 @@
 #include "Timer.hh"
 #include "GraphicsPointer.hh"
 
+/**
+ * A projectile is a flying PhysicsObject, created by firing a player's weapon. It has an initial velocity, is
+ * represented as a diamond-shape with the given "radius", can explode or bounce on collisions, expires at some point,
+ * and can remove ground around it upon exploding.
+ */
 class Projectile : public PhysicsObject {
 protected:
     /**
diff -r e0e4dfc3e528 -r 7540b0859579 src/Rope.hh
--- a/src/Rope.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/Rope.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -9,12 +9,21 @@
 #include "PhysicsObject.hh"
 #include "GraphicsPointer.hh"
 
+/**
+ * The rope can be in one of three states...
+ *
+ * @see Rope
+ */
 enum RopeState {
-    ROPE_FOLDED, 
-    ROPE_FLYING, 
-    ROPE_FIXED 
+    ROPE_FOLDED,    //<<< The rope is folded, out of sight, and not in use
+    ROPE_FLYING,    //<<< The rope is flying through the air as a projectile
+    ROPE_FIXED      //<<< The rope is attached to something
 };
 
+/**
+ * A rope is a PhysicsObject that can be thrown, whereupon it then flies until it hits something, whereupon
+ * it attaches to that, and sets itself as the player's pivot.
+ */
 class Rope : public PhysicsObject {
 private:
     // the owner
diff -r e0e4dfc3e528 -r 7540b0859579 src/SinglePlayer.hh
--- a/src/SinglePlayer.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/SinglePlayer.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -3,6 +3,9 @@
 
 #include "GameState.hh"
 
+/**
+ * Simple class used to define the LocalPlayer used by Engine to run a local non-network game
+ */
 class SinglePlayer : public LocalPlayer {
     public:
         SinglePlayer (GameState &state) :
diff -r e0e4dfc3e528 -r 7540b0859579 src/Timer.hh
--- a/src/Timer.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/Timer.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -3,9 +3,20 @@
 
 #include <ClanLib/core.h>
 
+/**
+ * A time interval, measured in real milliseconds
+ */
 typedef unsigned long TimeMS;
+
+/**
+ * Abstract tick count, defined as a number of Timer::interval's against real time
+ */
 typedef uint32_t TickCount;
 
+/**
+ * Used to implement Physics ticks and Graphics frames. This will attempt to trigger sig_tick every <interval> ms,
+ * but if we miss some ticks or something else, then the tick_length passed to sig_tick will be longer than interval...
+ */
 class Timer : public CL_KeepAlive {
     protected:
         // the target tick interval
diff -r e0e4dfc3e528 -r 7540b0859579 src/Weapon.hh
--- a/src/Weapon.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/Weapon.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -10,6 +10,11 @@
 #include "Timer.hh"
 #include <string>
 
+/**
+ * A Weapon is something that a Player has in their list of weapons. It has a name, some parameters related to the
+ * weapon itself (name, reload time), and some parameters related to the projectiles that it creates (velocity,
+ * radius, etc).
+ */
 class Weapon {
 protected:
     /**
diff -r e0e4dfc3e528 -r 7540b0859579 src/Weapons.hh
--- a/src/Weapons.hh	Mon Dec 08 12:02:20 2008 +0000
+++ b/src/Weapons.hh	Mon Dec 08 12:46:37 2008 +0000
@@ -5,7 +5,7 @@
 #include <vector>
 
 /**
- * A collection of simple weapons
+ * Return a collection of simple weapons
  */
 std::vector<Weapon*> buildWeaponsList (void);