Improved documentation

include/Camera.h

@@ -1,40 +1,9 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file include/Camera.h
+ * \brief OpenGL camera class
  *
- * Project : Hel
- * Author  : Mongoose
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  : Camera
- * License : No use w/o permission (C) 2001 Mongoose
- * Comments: OpenGL camera class for Freyja
- *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- History ------------------------------------------------
- *
- * 2002.12.16:
- * Mongoose - Removed perspective setting and OpenGL dependency
- *            API changes to reflect new direction of this object:
- *              Removing outdated algorithms and code
- *              And refactoring the class in general
- *
- * 2001.06.06:
- * Mongoose - Moving GLU code into here to setup break up
- *            into Camera base class, DynamicCamera,
- *            and GLUCamera child classes
- *
- * 2001.06.04:
- * Mongoose - Quaternion based compile option
- *
- * 2001.05.18:
- * Mongoose - Created, based on my old GL camera code
- *            that has been used in GooseEgg since alpha
- *            and algorithms from Yuri Zhivago's trview
- ================================================================*/
-
-
+ * \author Mongoose
+ */
 #ifndef _CAMERA_H_
 #define _CAMERA_H_
 
@@ -42,8 +11,10 @@
 #include <Matrix.h>
 #include <Quaternion.h>
 
-enum camera_command                /* Interactive camera control */
-{
+/*!
+ * \brief Commands for interactive camera control
+ */
+enum camera_command {
   CAMERA_MOVE_FORWARD = 1,
   CAMERA_MOVE_BACKWARD,
   CAMERA_MOVE_UP,
@@ -58,102 +29,81 @@ enum camera_command                /* Interactive camera control */
   CAMERA_MOVE_RIGHT
 };
 
-enum CameraFlags
-{
-    Camera_FlyMode = 1
+/*!
+ * \brief Flags a camera can have
+ */
+enum CameraFlags {
+    Camera_FlyMode = (1 << 0) //!< Camera is flying free?
 };
 
-
-class Camera
-{
- public:
-
-    ////////////////////////////////////////////////////////////
-    // Constructors
-    ////////////////////////////////////////////////////////////
-
+/*!
+ * \brief OpenGL camera class
+ *
+ * 2002.12.16:
+ * Mongoose - Removed perspective setting and OpenGL dependency
+ *            API changes to reflect new direction of this object:
+ *              Removing outdated algorithms and code
+ *              And refactoring the class in general
+ *
+ * 2001.06.06:
+ * Mongoose - Moving GLU code into here to setup break up
+ *            into Camera base class, DynamicCamera,
+ *            and GLUCamera child classes
+ *
+ * 2001.06.04:
+ * Mongoose - Quaternion based compile option
+ *
+ * 2001.05.18:
+ * Mongoose - Created, based on my old GL camera code
+ *            that has been used in GooseEgg since alpha
+ *            and algorithms from Yuri Zhivago's trview
+ */
+class Camera {
+public:
+    /*!
+     * \brief Constructs an object of Camera
+     */
     Camera();
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Constructs an object of Camera
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.18:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Deconstructs an object of Camera
+     */
     ~Camera();
-    /*------------------------------------------------------
-     * Pre  : Camera object is allocated
-     * Post : Deconstructs an object of Camera
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.18:
-     * Mongoose - Created
-     ------------------------------------------------------*/
-
-
-    ////////////////////////////////////////////////////////////
-    // Public Accessors
-    ////////////////////////////////////////////////////////////
 
+    /*!
+     * \brief Get this cameras ID
+     * \returns id
+     */
     unsigned int getId();
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Returns this camera's id
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.18:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Returns the current position
+     * \param pos where the position will be stored
+     */
     void getPosition(vec3_t pos);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Returns current position
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.06.16:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Returns the up vector
+     * \param up where the up vector will be stored
+     */
     void getUp(vec3_t up);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Returns up vector
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.18:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Get the target currently looked at
+     * \param target where the target will be stored
+     */
     void getTarget(vec3_t target);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Returns target ( look at pos )
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.18:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Get current yaw in degrees
+     * \returns yaw in degrees
+     */
     float getYaw();
-    /*------------------------------------------------------
-     * Pre  : Get current yaw in degrees
-     * Post :
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.06.22:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Get angle/yaw of camera
+     * \returns theta angle/yaw of camera
+     */
     double getRadianYaw();
     /*------------------------------------------------------
      * Pre  :
@@ -165,206 +115,111 @@ class Camera
      * Mongoose - Created
      ------------------------------------------------------*/
 
+    /*!
+     * \brief Get current angle/pitch
+     * \returns current pitch in degrees
+     */
     float getPitch();
-    /*------------------------------------------------------
-     * Pre  : Get current pitch in degrees
-     * Post :
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.06.22:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Get angle/pitch of camera
+     * \returns phi angle/pitch of camera
+     */
     double getRadianPitch();
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Returns phi angle/pitch of camera
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.26:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Check if the coordinate is behind camera eye
+     * \param x X coordinate to check
+     * \param z Z coordinate to check
+     * \returns true if (x, z) is behind camera eye
+     */
     bool isBehind(int x, int z);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Returns true if (x, z) is behind camera eye
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.26:
-     * Mongoose - Created
-     ------------------------------------------------------*/
-
-
-    ////////////////////////////////////////////////////////////
-    // Public Mutators
-    ////////////////////////////////////////////////////////////
 
+    /*!
+     * \brief Rotate the camera
+     * \param angle angle in radians
+     * \param x X coordinate of axis
+     * \param y Y coordinate of axis
+     * \param z Z coordinate of axis
+     */
     void rotate(float angle, float x, float y, float z);
-    /*------------------------------------------------------
-     * Pre  : x,y,z axis; angle in radians
-     * Post : Rotates camera
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.06.04:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Set Camera position
+     * \param x new X coordinate
+     * \param y new Y coordinate
+     * \param z new Z coordinate
+     */
     void translate(float x, float y, float z);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Camera position is set to x,y,z
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.18:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Set the Camera to its initial state
+     */
     void reset();
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Camera is set to inital state
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.18:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Sets the X rotation delta
+     * \param angle thetas rotation delta in degrees
+     */
     void setSensitivityX(float angle);
-    /*------------------------------------------------------
-     * Pre  : angle is theta's rotation delta in degrees
-     * Post : Sets rotation delta
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.06.04:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Sets the Y rotation delta
+     * \param angle thetas rotation delta in degrees
+     */
     void setSensitivityY(float angle);
-    /*------------------------------------------------------
-     * Pre  : angle is theta's rotation delta in degrees
-     * Post : Sets rotation delta
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.06.04:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Sends interactive command to camera
+     * \param cmd valid camera command
+     */
     void command(enum camera_command cmd);
-    /*------------------------------------------------------
-     * Pre  : Command is valid camera command
-     * Post : Sends interactive command to camera
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.18:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
-   void setSpeed(float s);
-   /*------------------------------------------------------
-    * Pre  : s is 256 or greater in general
-    * Post : Sets 'speed'
-    *
-    *-- History ------------------------------------------
-    *
-    * 2002.01.02:
-    * Mongoose - Created
-    ------------------------------------------------------*/
+    /*!
+     * \brief Sets speed
+     * \param s new speed, is 256 or greater in general
+     */
+    void setSpeed(float s);
 
+    /*!
+     * \brief Updates view target
+     */
     void update();
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Updates view target
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.18:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Set current position
+     * \param pos new position
+     */
     void setPosition(vec3_t pos);
-    /*------------------------------------------------------
-     * Pre  : Set current position
-     * Post :
-     *
-     *-- History ------------------------------------------
-     *
-     * 2002.06.16:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Sets the up vector
+     * \param up new up vector
+     */
     void setUp(vec3_t up);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Sets up vector
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.18:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+    /*!
+     * \brief Sets target (look at pos)
+     * \param target new target
+     */
     void setTarget(vec3_t target);
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Sets target ( look at pos )
-     *
-     *-- History ------------------------------------------
-     *
-     * 2001.05.18:
-     * Mongoose - Created
-     ------------------------------------------------------*/
-
-
- private:
-
-    ////////////////////////////////////////////////////////////
-    // Private Accessors
-    ////////////////////////////////////////////////////////////
-
-
-    ////////////////////////////////////////////////////////////
-    // Private Mutators
-    ////////////////////////////////////////////////////////////
-
-    unsigned int mId;           /* Unquie id */
-
-    Quaternion mQ;              /* Quaternion for rotation */
-
-    unsigned int mFlags;        /* For testing with flags  */
-
-    double mPos[4];             /* Location in 3 space (aka eye) */
-
-    double mTarget[4];          /* Postition we're looking at  */
-
-    double mUp[4];              /* Up vector  */
-
-    double mSide[4];            /* Side vector  */
-
-    double mViewDistance;      /* Distance from target */
-
-    double mTranslateDelta;    /* Step size to move */
-
-    double mRotateDelta;       /* Radians to rotate  Y */
-
-    double mTheta;              /* View angle  Y */
-
-    double mRotateDelta2;      /* Radians to rotate  Z */
-
-    double mTheta2;             /* View angle  Z */
-
-    bool mUpdate;               /* Check to see if view needs updating */
 
-    static unsigned int mCounter;   /* Id system use */
+private:
+    unsigned int mId;             //!< Unique id
+    Quaternion mQ;                //!< Quaternion for rotation
+    unsigned int mFlags;          //!< For testing with flags
+    double mPos[4];               //!< Location in 3 space (aka eye)
+    double mTarget[4];            //!< Postition we're looking at
+    double mUp[4];                //!< Up vector
+    double mSide[4];              //!< Side vector
+    double mViewDistance;         //!< Distance from target
+    double mTranslateDelta;       //!< Step size to move
+    double mRotateDelta;          //!< Radians to rotate Y
+    double mTheta;                //!< View angle Y
+    double mRotateDelta2;         //!< Radians to rotate Z
+    double mTheta2;               //!< View angle Z
+    bool mUpdate;                 //!< Check to see if view needs updating
+    static unsigned int mCounter; //!< Id system use
 };
 
 #endif

include/SkeletalModel.h

@@ -2,8 +2,6 @@
  * \file include/SkeletalModel.h
  * \brief This is the factored out skeletal model class
  *
- * Defining UNIT_TEST_SKELETALMODEL builds SkeletalModel class as a console unit test
- *
  * \author Mongoose
  *
  * \todo Start cutting off old hacks by simple force use of method interface.
@@ -17,37 +15,26 @@
 #include <Vector.h>
 #include <MatMath.h>
 
-
-typedef struct bone_tag_s
-{
+typedef struct {
     int mesh;
     vec3_t off;
     vec3_t rot;
     char flag;
-
 } bone_tag_t;
 
-
-typedef struct bone_frame_s
-{
+typedef struct {
     Vector<bone_tag_t *> tag;
     vec3_t pos;
     float yaw;
-
 } bone_frame_t;
 
-
-typedef struct animation_frame_s
-{
+typedef struct {
     int id;
     char rate;
     Vector<bone_frame_t *> frame;
-
 } animation_frame_t;
 
-
-typedef struct skeletal_model_s
-{
+typedef struct {
     int id;
     bool tr4Overlay;
     bool pigtails;
@@ -59,56 +46,29 @@ typedef struct skeletal_model_s
     float ponyOff;
     float ponyOff2;
     Vector<animation_frame_t *> animation;
-
 } skeletal_model_t;
 
-
-class SkeletalModel
-{
- public:
-
-    ////////////////////////////////////////////////////////////
-    // Constructors
-    ////////////////////////////////////////////////////////////
-
+/*!
+ * \brief This is the factored out skeletal model class
+ */
+class SkeletalModel {
+public:
+    /*!
+     * \brief Constructs an object of SkeletalModel
+     */
     SkeletalModel();
-    /*------------------------------------------------------
-     * Pre  :
-     * Post : Constructs an object of SkeletalModel
-     *
-     *-- History ------------------------------------------
-     *
-     * 2003.05.19:
-     * Mongoose - Created
-     ------------------------------------------------------*/
 
+     /*!
+     * \brief Deconstructs an object of SkeletalModel
+     */
     ~SkeletalModel();
-    /*------------------------------------------------------
-     * Pre  : SkeletalModel object is allocated
-     * Post : Deconstructs an object of SkeletalModel
-     *
-     *-- History ------------------------------------------
-     *
-     * 2003.05.19:
-     * Mongoose - Created
-     ------------------------------------------------------*/
-
-
-    ////////////////////////////////////////////////////////////
-    // Public Accessors
-    ////////////////////////////////////////////////////////////
 
     int getAnimation();
 
-    int getFrame() ;
+    int getFrame();
 
     int getIdleAnimation();
 
-
-    ////////////////////////////////////////////////////////////
-    // Public Mutators
-    ////////////////////////////////////////////////////////////
-
     void setModel(skeletal_model_t *mdl);
 
     void setAnimation(int index);
@@ -117,33 +77,16 @@ class SkeletalModel
 
     void setIdleAnimation(int index);
 
-
-    enum SkeletalModelFlag { fReserved = 1 };
-
     unsigned int flags;
-
-    skeletal_model_t *model;   /* World render model */
-
-    float time;                /* Interpolation use */
+    skeletal_model_t *model; //!< World render model
+    float time;              //!< Interpolation use
     float lastTime;
-
-    float rate; // temp cache this here for old animation system use
+    float rate;              //!< \fixme temp cache this here for old animation system use
 
 private:
-
-    ////////////////////////////////////////////////////////////
-    // Private Accessors
-    ////////////////////////////////////////////////////////////
-
-
-    ////////////////////////////////////////////////////////////
-    // Private Mutators
-    ////////////////////////////////////////////////////////////
-
-
-    int mBoneFrame;             /* Bone frame */
-    int mAnimationFrame;        /* Animation frame */
-    int mIdleAnimation;         /* Idle animation */
+    int mBoneFrame;      //!< Bone frame
+    int mAnimationFrame; //!< Animation frame
+    int mIdleAnimation;  //!< Idle animation
 };
 
 #endif

include/tga.h

@@ -29,19 +29,18 @@ typedef enum {
  * \brief Data structure representing TGA file header
  */
 typedef struct {
-    unsigned char comment_lenght;       /*!< Number of bytes in comment */
-    unsigned char colormap_type;        /*!< 0 No colormap; 1 Has colormap  */
-    unsigned char image_type;           /*!< 1 Colormapped; 2 Unmapped;
-                                             9 Colormapped RLE; 10 Unmapped RLE */
-    unsigned short colormap_index;      /*!< Index of first color map entry */
-    unsigned short colormap_lenght;     /*!< Number of color map entries */
-    unsigned char colormap_bbp;         /*!< 16, 24, or 32 bits per pixel format */
-    unsigned short origin_x;            /*!< X coor of lower-left corner */
-    unsigned short origin_y;            /*!< Y coor of lower-left corner */
-    unsigned short width;               /*!< Width in pixels */
-    unsigned short height;              /*!< Height in pixels */
-    unsigned char bpp;                  /*!< Number of bits in a pixel index */
-    unsigned char desc_flags;           /*!< Various magic bits */
+    unsigned char comment_lenght;       //!< Number of bytes in comment
+    unsigned char colormap_type;        //!< 0 No colormap; 1 Has colormap
+    unsigned char image_type;           //!< 1 Colormapped; 2 Unmapped; 9 Colormapped RLE; 10 Unmapped RLE
+    unsigned short colormap_index;      //!< Index of first color map entry
+    unsigned short colormap_lenght;     //!< Number of color map entries
+    unsigned char colormap_bbp;         //!< 16, 24, or 32 bits per pixel format
+    unsigned short origin_x;            //!< X coor of lower-left corner
+    unsigned short origin_y;            //!< Y coor of lower-left corner
+    unsigned short width;               //!< Width in pixels
+    unsigned short height;              //!< Height in pixels
+    unsigned char bpp;                  //!< Number of bits in a pixel index
+    unsigned char desc_flags;           //!< Various magic bits
 } tga_t;
 
 /*!

src/Camera.cpp

@@ -1,36 +1,9 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file src/Camera.cpp
+ * \brief OpenGL camera class
  *
- * Project : Freyja
- * Author  : Mongoose
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  : Camera
- * License : No use w/o permission (C) 2001 Mongoose
- * Comments: OpenGL camera class for Freyja
- *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- History -------------------------------------------------
- *
- * 2002.12.16:
- * Mongoose - Removed perspective setting and OpenGL dependency
- *            API changes to reflect new direction of this object:
- *              Removing outdated algorithms and code
- *              And refactoring the class in general
- *
- * 2001.06.06:
- * Mongoose - Moving GLU code into here to setup break up
- *            into Camera base class, DynamicCamera,
- *            and GLUCamera child classes
- *
- * 2001.06.04:
- * Mongoose - Quaternion based compile option
- *
- * 2001.05.18:
- * Mongoose - Created
- =================================================================*/
+ * \author Mongoose
+ */
 
 #include <stdio.h>
 #include <math.h>

src/SkeletalModel.cpp

@@ -1,23 +1,9 @@
-/* -*- Mode: C++; tab-width: 3; indent-tabs-mode: t; c-basic-offset: 3 -*- */
-/*================================================================
+/*!
+ * \file src/SkeletalModel.cpp
+ * \brief This is the factored out skeletal model class
  *
- * Project : OpenRaider
- * Author  : Terry 'Mongoose' Hendrix II
- * Website : http://www.westga.edu/~stu7440/
- * Email   : stu7440@westga.edu
- * Object  : SkeletalModel
- * License : No use w/o permission (C) 2003 Mongoose
- * Comments: This is the factored out skeletal model class
- *
- *
- *           This file was generated using Mongoose's C++
- *           template generator script.  <stu7440@westga.edu>
- *
- *-- History -------------------------------------------------
- *
- * 2003.05.19:
- * Mongoose - Created
- =================================================================*/
+ * \author Mongoose
+ */
 
 #include <SkeletalModel.h>