From a394c9efec830b275c0b738974126aead284ec4e Mon Sep 17 00:00:00 2001
From: Piotr Dziwinski <piotrdz@gmail.com>
Date: Thu, 27 Sep 2012 20:43:20 +0200
Subject: [PATCH] Updated docs and some Doxygen fixes

---
 Doxyfile                        |  3 +--
 src/app/README.txt              |  2 +-
 src/app/app.h                   |  2 +-
 src/common/README.txt           |  2 +-
 src/common/event.h              |  2 +-
 src/common/iman.h               |  2 +-
 src/graphics/README.txt         |  4 ++--
 src/graphics/d3d/README.txt     |  5 +----
 src/graphics/engine/README.txt  |  4 ++--
 src/graphics/engine/engine.h    |  6 ++---
 src/graphics/engine/lightman.h  | 39 ++++++++++++++++++---------------
 src/graphics/engine/terrain.cpp |  8 ++++---
 src/graphics/opengl/README.txt  |  4 ++--
 src/math/README.txt             |  4 ++--
 src/math/geometry.h             |  5 ++++-
 src/object/README.txt           |  4 ++--
 src/physics/README.txt          |  4 ++--
 src/sound/README.txt            |  4 ++--
 src/ui/README.txt               |  4 ++--
 19 files changed, 56 insertions(+), 52 deletions(-)

diff --git a/Doxyfile b/Doxyfile
index cdbf278d..8c5fffe4 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -700,8 +700,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = "src/old" \
-                         "src/metafile"
+EXCLUDE                = "src/CBot/tests"
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
diff --git a/src/app/README.txt b/src/app/README.txt
index e4f69ec8..92be8a6b 100644
--- a/src/app/README.txt
+++ b/src/app/README.txt
@@ -1,4 +1,4 @@
 /**
- * \dir app
+ * \dir src/app
  * Main class of the application and system functions
  */
diff --git a/src/app/app.h b/src/app/app.h
index f1e2c7fc..e887a63f 100644
--- a/src/app/app.h
+++ b/src/app/app.h
@@ -75,7 +75,7 @@ enum VideoQueryResult
 
 
 /**
- * \enum TrackedKeys
+ * \enum TrackedKey
  * \brief Additional keys whose state (pressed/released) is tracked by CApplication
  */
 enum TrackedKey
diff --git a/src/common/README.txt b/src/common/README.txt
index 73d65b73..25c9fbf3 100644
--- a/src/common/README.txt
+++ b/src/common/README.txt
@@ -1,4 +1,4 @@
 /**
- * \dir common
+ * \dir src/common
  * \brief Structs and utils shared throughout the application
  */
diff --git a/src/common/event.h b/src/common/event.h
index dc50ee6e..ce2872ad 100644
--- a/src/common/event.h
+++ b/src/common/event.h
@@ -81,7 +81,7 @@ enum WheelDirection
 };
 
 /**
- * \enum MouseWheelEventData
+ * \struct MouseWheelEventData
  * \brief Additional data for mouse wheel event.
  */
 struct MouseWheelEventData
diff --git a/src/common/iman.h b/src/common/iman.h
index 44f143a0..75655aa9 100644
--- a/src/common/iman.h
+++ b/src/common/iman.h
@@ -95,7 +95,7 @@ enum ManagedClassType
 
 
 /**
- * \enum ManagedClassInstances
+ * \struct ManagedClassInstances
  * \brief Instances of class managed by CInstanceManager
  */
 struct ManagedClassInstances
diff --git a/src/graphics/README.txt b/src/graphics/README.txt
index 479747b9..1cb91ba9 100644
--- a/src/graphics/README.txt
+++ b/src/graphics/README.txt
@@ -1,5 +1,5 @@
 /**
- * \dir graphics
+ * \dir src/graphics
  * \brief Graphics engine
  */
 
@@ -9,4 +9,4 @@
  *
  * This namespace was created to avoid clashing with old code, but now it still serves,
  * defining a border between pure graphics engine and other parts of application.
- */
\ No newline at end of file
+ */
diff --git a/src/graphics/d3d/README.txt b/src/graphics/d3d/README.txt
index 524ae7bb..0fe7db68 100644
--- a/src/graphics/d3d/README.txt
+++ b/src/graphics/d3d/README.txt
@@ -1,4 +1 @@
-/**
- * \dir graphics/d3d
- * \brief Possible future DirectX implementation of graphics engine
- */
\ No newline at end of file
+Possible future DirectX implementation of graphics engine
diff --git a/src/graphics/engine/README.txt b/src/graphics/engine/README.txt
index f64d3dda..05d2d76f 100644
--- a/src/graphics/engine/README.txt
+++ b/src/graphics/engine/README.txt
@@ -1,9 +1,9 @@
 /**
- * \dir graphics/engine
+ * \dir src/graphics/engine
  * \brief Graphics engine
  *
  * CEngine class and various other classes implementing the main features
  * of graphics engine from model loading to decorative particles
  *
  * Graphics operations are done on abstract interface from src/graphics/core
- */
\ No newline at end of file
+ */
diff --git a/src/graphics/engine/engine.h b/src/graphics/engine/engine.h
index e36865c9..c35b7a53 100644
--- a/src/graphics/engine/engine.h
+++ b/src/graphics/engine/engine.h
@@ -568,7 +568,7 @@ struct EngineMouse
  *
  * It uses a lower-level CDevice object which is implementation-independent core engine.
  *
- * \section 3DScene 3D Scene
+ * \section Scene 3D Scene
  *
  * The 3D scene is drawn with view coordinates set from camera position in 3D space and
  * a perspective projection matrix. The world matrix depends on the object drawn.
@@ -588,7 +588,7 @@ struct EngineMouse
  *  - mouse cursor
  *  - animated highlight box of the selected object(s)
  *
- * \section 2DInterface 2D Interface
+ * \section Interface 2D Interface
  *
  * The 2D interface is drawn in fixed XY coordinates, independent from window size.
  * Lower-left corner of the screen is (0,0) and upper-right corner is (1,1).
@@ -601,7 +601,7 @@ struct EngineMouse
  * are instances of CControl class. The source code for these classes is in
  * src/ui directory.
  *
- * \section Objecs Engine Objects
+ * \section Objects Engine Objects
  *
  * The 3D scene is composed of objects which are basically collections of triangles forming
  * a surface or simply independent triangles in space.
diff --git a/src/graphics/engine/lightman.h b/src/graphics/engine/lightman.h
index 3b96e51c..d83dfb37 100644
--- a/src/graphics/engine/lightman.h
+++ b/src/graphics/engine/lightman.h
@@ -34,8 +34,9 @@
 namespace Gfx {
 
 /**
-  \struct LightProgression
-  \brief Describes the progression of light parameters change */
+ * \struct LightProgression
+ * \brief Describes the progression of light parameters change
+ */
 struct LightProgression
 {
     //! Starting value
@@ -75,11 +76,12 @@ enum LightPriority
 };
 
 /**
-  \struct DynamicLight
-  \brief Dynamic light in 3D scene
-
-  It is an extension over standard light properties. Added are dynamic progressions for light
-  colors and intensity and types of objects included/excluded in lighting. */
+ * \struct DynamicLight
+ * \brief Dynamic light in 3D scene
+ *
+ * It is an extension over standard light properties. Added are dynamic progressions for light
+ * colors and intensity and types of objects included/excluded in lighting.
+ */
 struct DynamicLight
 {
     //! Whether the light is used
@@ -111,17 +113,18 @@ struct DynamicLight
 };
 
 /**
-  \class CLightManager
-  \brief Manager for dynamic lights in 3D scene
-
-  (Old CLight class)
-
-  The class is responsible for managing dynamic lights (struct DynamicLight) used in 3D scene.
-  The dynamic lights are created, updated and deleted through the class' interface.
-
-  Number of available lights depends on graphics device used. Class allocates vector
-  for the total number of lights, but only some are used.
-  */
+ * \class CLightManager
+ * \brief Manager for dynamic lights in 3D scene
+ *
+ * The class is responsible for managing dynamic lights (struct DynamicLight) used in 3D scene.
+ * The dynamic lights are created, updated and deleted through the class' interface.
+ *
+ * Since there is a limit on total number of lights available in OpenGL (usually up to 8), the dynamic lights
+ * must be emulated by displaying only some of them. All functions normally operate only on DynamicLight structs,
+ * updating the models with new values, while only one function, UpdateDeviceLights(), performs the actual
+ * synchronization to the device. It allocates device's light slots as necessary, with two priority levels
+ * for lights.
+ */
 class CLightManager
 {
 public:
diff --git a/src/graphics/engine/terrain.cpp b/src/graphics/engine/terrain.cpp
index 9a82c1fa..4c22a32e 100644
--- a/src/graphics/engine/terrain.cpp
+++ b/src/graphics/engine/terrain.cpp
@@ -1455,7 +1455,8 @@ bool CTerrain::AdjustToFloor(Math::Vector &pos, bool brut, bool water)
 }
 
 /**
- * @returns \c false if the initial coordinate was outside terrain area; \c true otherwise
+ * \param pos position to adjust
+ * \returns \c false if the initial coordinate was outside terrain area; \c true otherwise
  */
 bool CTerrain::AdjustToStandardBounds(Math::Vector& pos)
 {
@@ -1492,8 +1493,9 @@ bool CTerrain::AdjustToStandardBounds(Math::Vector& pos)
 }
 
 /**
- * @param margin margin to the terrain border
- * @returns \c false if the initial coordinate was outside terrain area; \c true otherwise
+ * \param pos position to adjust
+ * \param margin margin to the terrain border
+ * \returns \c false if the initial coordinate was outside terrain area; \c true otherwise
  */
 bool CTerrain::AdjustToBounds(Math::Vector& pos, float margin)
 {
diff --git a/src/graphics/opengl/README.txt b/src/graphics/opengl/README.txt
index 596871d4..c62166be 100644
--- a/src/graphics/opengl/README.txt
+++ b/src/graphics/opengl/README.txt
@@ -1,7 +1,7 @@
 /**
- * \dir graphics/opengl
+ * \dir src/graphics/opengl
  * \brief OpenGL engine implementation
  *
  * Contains the concrete implementation using OpenGL of abstract CDevice class
  * from src/graphics/core
- */
\ No newline at end of file
+ */
diff --git a/src/math/README.txt b/src/math/README.txt
index fd34dcbe..26069aaa 100644
--- a/src/math/README.txt
+++ b/src/math/README.txt
@@ -1,5 +1,5 @@
 /**
- * \dir math
+ * \dir src/math
  * \brief Common mathematical structures and functions
  */
 
@@ -9,4 +9,4 @@
  *
  * This namespace was created to avoid clashing with old code, but now it still serves,
  * defining a border between math and non-math-related code.
- */
\ No newline at end of file
+ */
diff --git a/src/math/geometry.h b/src/math/geometry.h
index f086e2d1..ee6fc527 100644
--- a/src/math/geometry.h
+++ b/src/math/geometry.h
@@ -237,6 +237,7 @@ inline float RotateAngle(const Math::Point &center, const Math::Point &p1, const
 
 //! Loads view matrix from the given vectors
 /**
+ * \param mat      result matrix
  * \param from     origin
  * \param at       view direction
  * \param worldUp  up vector
@@ -304,6 +305,7 @@ inline void LoadViewMatrix(Math::Matrix &mat, const Math::Vector &from,
 
 //! Loads a perspective projection matrix
 /**
+ * \param mat        result matrix
  * \param fov        field of view in radians
  * \param aspect     aspect ratio (width / height)
  * \param nearPlane  distance to near cut plane
@@ -328,6 +330,7 @@ inline void LoadProjectionMatrix(Math::Matrix &mat, float fov = Math::PI / 2.0f,
 
 //! Loads an othogonal projection matrix
 /**
+ * \param mat         result matrix
  * \param left,right  coordinates for left and right vertical clipping planes
  * \param bottom,top  coordinates for bottom and top horizontal clipping planes
  * \param zNear,zFar  distance to nearer and farther depth clipping planes
@@ -590,7 +593,7 @@ inline Math::Vector Transform(const Math::Matrix &m, const Math::Vector &p)
 
 //! Calculates the projection of the point \a p on a straight line \a a to \a b
 /**
- * \param point  to project
+ * \param p      point to project
  * \param a,b    two ends of the line
  */
 inline Math::Vector Projection(const Math::Vector &a, const Math::Vector &b, const Math::Vector &p)
diff --git a/src/object/README.txt b/src/object/README.txt
index f3bad238..fe946db5 100644
--- a/src/object/README.txt
+++ b/src/object/README.txt
@@ -1,7 +1,7 @@
 /**
- * \dir object
+ * \dir src/object
  * \brief Game engine
  *
  * Contains the main class of game engine - CRobotMain and the various in-game objects:
  * CObject and related auto, motion and task subclasses.
- */
\ No newline at end of file
+ */
diff --git a/src/physics/README.txt b/src/physics/README.txt
index 4ad59891..c068d4df 100644
--- a/src/physics/README.txt
+++ b/src/physics/README.txt
@@ -1,4 +1,4 @@
 /**
- * \dir physics
+ * \dir src/physics
  * \brief Physics engine
- */
\ No newline at end of file
+ */
diff --git a/src/sound/README.txt b/src/sound/README.txt
index fa7bbad9..fa2f5316 100644
--- a/src/sound/README.txt
+++ b/src/sound/README.txt
@@ -1,4 +1,4 @@
 /**
- * \dir sound
+ * \dir src/sound
  * \brief Sound module - playing sounds and music
- */
\ No newline at end of file
+ */
diff --git a/src/ui/README.txt b/src/ui/README.txt
index 9814ef0a..a159ed5c 100644
--- a/src/ui/README.txt
+++ b/src/ui/README.txt
@@ -1,4 +1,4 @@
 /**
- * \dir ui
+ * \dir src/ui
  * \brief 2D user interface controls
- */
\ No newline at end of file
+ */