7 files changed, 36 insertions, 34 deletions
diff --git a/src/graphics/README.txt b/src/graphics/README.txt
index 479747b..1cb91ba 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 524ae7b..0fe7db6 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 f64d3dd..05d2d76 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 e36865c..c35b7a5 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 3b96e51..d83dfb3 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 9a82c1f..4c22a32 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 596871d..c62166b 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
+ */