start adding some documentation, most core classes (outside of Network) are now doxygen-enabled
--- 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
--- 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
--- 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
--- 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;
--- 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;
--- 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;
--- 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:
};
--- 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:
/**
--- 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
--- 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) :
--- 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
--- 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:
/**
--- 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);