Documentation update

- updated Doxyfile
- added/changed file, dir and namespace descriptions
- fixed some errors in doxygen tags

Doxyfile

@@ -1,14 +1,14 @@
-# Doxyfile 1.8.0
+# Doxyfile 1.8.1.2
 
 # This file describes the settings to be used by the documentation system
-# doxygen (www.doxygen.org) for a project
+# doxygen (www.doxygen.org) for a project.
 #
-# All text after a hash (#) is considered a comment and will be ignored
+# All text after a hash (#) is considered a comment and will be ignored.
 # The format is:
 #       TAG = value [value, ...]
 # For lists items can also be appended using:
 #       TAG += value [value, ...]
-# Values that contain spaces should be placed between quotes (" ")
+# Values that contain spaces should be placed between quotes (" ").
 
 #---------------------------------------------------------------------------
 # Project related configuration options
@@ -372,8 +372,7 @@ EXTRACT_ALL            = NO
 
 EXTRACT_PRIVATE        = NO
 
-# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal
-# scope will be included in the documentation.
+# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal scope will be included in the documentation.
 
 EXTRACT_PACKAGE        = NO
 
@@ -564,12 +563,6 @@ MAX_INITIALIZER_LINES  = 30
 
 SHOW_USED_FILES        = YES
 
-# If the sources in your project are distributed over multiple directories 
-# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy 
-# in the documentation. The default is NO.
-
-SHOW_DIRECTORIES       = NO
-
 # Set the SHOW_FILES tag to NO to disable the generation of the Files page.
 # This will remove the Files entry from the Quick Index and from the
 # Folder Tree View (if specified). The default is YES.
@@ -577,7 +570,8 @@ SHOW_DIRECTORIES       = NO
 SHOW_FILES             = YES
 
 # Set the SHOW_NAMESPACES tag to NO to disable the generation of the
-# Namespaces page.  This will remove the Namespaces entry from the Quick Index 
+# Namespaces page.
+# This will remove the Namespaces entry from the Quick Index
 # and from the Folder Tree View (if specified). The default is YES.
 
 SHOW_NAMESPACES        = YES
@@ -594,7 +588,7 @@ FILE_VERSION_FILTER    =
 
 # The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
 # by doxygen. The layout file controls the global structure of the generated
-# output files in an output format independent way. The create the layout file 
+# output files in an output format independent way. To create the layout file
 # that represents doxygen's defaults, run doxygen with the -l option.
 # You can optionally specify a file name after the option, if omitted
 # DoxygenLayout.xml will be used as the name of the layout file.
@@ -630,7 +624,7 @@ WARNINGS               = YES
 # for undocumented members. If EXTRACT_ALL is set to YES then this flag will
 # automatically be disabled.
 
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 
 # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some
@@ -671,7 +665,8 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = "src" "src/CBot" "src/doc"
+INPUT                  = "src" \
+                         "src/CBot"
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -690,7 +685,8 @@ INPUT_ENCODING         = UTF-8
 # *.f90 *.f *.for *.vhd *.vhdl
 
 FILE_PATTERNS          = *.h \
-                         *.cpp
+                         *.cpp \
+                         README.txt
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories
 # should be searched for input files as well. Possible values are YES and NO.
@@ -704,7 +700,8 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = "src/old" "src/metafile"
+EXCLUDE                = "src/old" \
+                         "src/metafile"
 
 # 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
@@ -759,14 +756,17 @@ IMAGE_PATH             =
 # by executing (via popen()) the command <filter> <input-file>, where <filter>
 # is the value of the INPUT_FILTER tag, and <input-file> is the name of an
 # input file. Doxygen will then use the output that the filter program writes
-# to standard output.  If FILTER_PATTERNS is specified, this tag will be 
+# to standard output.
+# If FILTER_PATTERNS is specified, this tag will be
 # ignored.
 
 INPUT_FILTER           =
 
 # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
-# basis.  Doxygen will compare the file name with each pattern and apply the 
-# filter if there is a match.  The filters are a list of the form: 
+# basis.
+# Doxygen will compare the file name with each pattern and apply the
+# filter if there is a match.
+# The filters are a list of the form:
 # pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further
 # info on how filters are used. If FILTER_PATTERNS is empty or if
 # non of the patterns match the file name, INPUT_FILTER is applied.
@@ -805,7 +805,7 @@ INLINE_SOURCES         = NO
 
 # Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
 # doxygen to hide any special comment blocks from generated source code
-# fragments. Normal C and C++ comments will always remain visible.
+# fragments. Normal C, C++ and Fortran comments will always remain visible.
 
 STRIP_CODE_COMMENTS    = YES
 
@@ -824,7 +824,8 @@ REFERENCES_RELATION    = NO
 # If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
 # and SOURCE_BROWSER tag is set to YES, then the hyperlinks from
 # functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will
-# link to the source code.  Otherwise they will link to the documentation.
+# link to the source code.
+# Otherwise they will link to the documentation.
 
 REFERENCES_LINK_SOURCE = YES
 
@@ -889,7 +890,7 @@ HTML_FILE_EXTENSION    = .html
 # The HTML_HEADER tag can be used to specify a personal HTML header for
 # each generated HTML page. If it is left blank doxygen will generate a
 # standard header. Note that when using a custom header you are responsible
-# for the proper inclusion of any scripts and style sheets that doxygen 
+#  for the proper inclusion of any scripts and style sheets that doxygen
 # needs, which is dependent on the configuration options used.
 # It is advised to generate a default header using "doxygen -w html
 # header.html footer.html stylesheet.css YourConfigFile" and then modify
@@ -954,20 +955,23 @@ HTML_COLORSTYLE_GAMMA  = 80
 
 HTML_TIMESTAMP         = YES
 
-# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, 
-# files or namespaces will be aligned in HTML using tables. If set to 
-# NO a bullet list will be used.
-
-HTML_ALIGN_MEMBERS     = YES
-
 # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
 # documentation will contain sections that can be hidden and shown after the
-# page has loaded. For this to work a browser that supports 
-# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox 
-# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari).
+# page has loaded.
 
 HTML_DYNAMIC_SECTIONS  = NO
 
+# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of
+# entries shown in the various tree structured indices initially; the user
+# can expand and collapse entries dynamically later on. Doxygen will expand
+# the tree to such a level that at most the specified number of entries are
+# visible (unless a fully collapsed tree already exceeds this amount).
+# So setting the number of entries 1 will produce a full collapsed tree by
+# default. 0 is a special value representing an infinite number of entries
+# and will result in a full expanded tree by default.
+
+HTML_INDEX_NUM_ENTRIES = 100
+
 # If the GENERATE_DOCSET tag is set to YES, additional index files
 # will be generated that can be used as input for Apple's Xcode 3
 # integrated development environment, introduced with OSX 10.5 (Leopard).
@@ -1103,7 +1107,7 @@ QHP_SECT_FILTER_ATTRS  =
 QHG_LOCATION           =
 
 # If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files
-# will be generated, which together with the HTML files, form an Eclipse help 
+#  will be generated, which together with the HTML files, form an Eclipse help
 # plugin. To install this plugin and make it available under the help contents
 # menu in Eclipse, the contents of the directory containing the HTML and XML
 # files needs to be copied into the plugins directory of eclipse. The name of
@@ -1146,11 +1150,6 @@ GENERATE_TREEVIEW      = NO
 
 ENUM_VALUES_PER_LINE   = 4
 
-# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, 
-# and Class Hierarchy pages using a tree view instead of an ordered list.
-
-USE_INLINE_TREES       = NO
-
 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
 # used to set the initial width (in pixels) of the frame in which the tree
 # is shown.
@@ -1193,7 +1192,8 @@ USE_MATHJAX            = NO
 # directory is located at the same level as the HTML output directory, then
 # MATHJAX_RELPATH should be ../mathjax. The default value points to
 # the MathJax Content Delivery Network so you can quickly see the result without
-# installing MathJax.  However, it is strongly recommended to install a local 
+# installing MathJax.
+# However, it is strongly recommended to install a local
 # copy of MathJax from http://www.mathjax.org before deployment.
 
 MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
@@ -1458,8 +1458,10 @@ GENERATE_PERLMOD       = NO
 PERLMOD_LATEX          = NO
 
 # If the PERLMOD_PRETTY tag is set to YES the Perl module output will be
-# nicely formatted so it can be parsed by a human reader.  This is useful 
-# if you want to understand what is going on.  On the other hand, if this 
+# nicely formatted so it can be parsed by a human reader.
+# This is useful
+# if you want to understand what is going on.
+# On the other hand, if this
 # tag is set to NO the size of the Perl module output will be much smaller
 # and Perl will parse it just the same.
 
@@ -1545,9 +1547,11 @@ SKIP_FUNCTION_MACROS   = YES
 # The TAGFILES option can be used to specify one or more tagfiles. For each
 # tag file the location of the external documentation should be added. The
 # format of a tag file without this location is as follows:
-#   TAGFILES = file1 file2 ... 
+#
+# TAGFILES = file1 file2 ...
 # Adding location for the tag files is done as follows:
-#   TAGFILES = file1=loc1 "file2 = loc2" ... 
+#
+# TAGFILES = file1=loc1 "file2 = loc2" ...
 # where "loc1" and "loc2" can be relative or absolute paths
 # or URLs. Note that each tag file must have a unique name (where the name does
 # NOT include the path). If a tag file is not located in the directory in which
@@ -1713,7 +1717,7 @@ CALLER_GRAPH           = NO
 
 GRAPHICAL_HIERARCHY    = YES
 
-# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES 
+# If the DIRECTORY_GRAPH and HAVE_DOT tags are set to YES
 # then doxygen will show the dependencies a directory has on other directories
 # in a graphical way. The dependency relations are determined by the #include
 # relations between the files in the directories.

src/app/README.txt

@@ -1,3 +1,4 @@
-src/app
-
-Contains the main class of the application.
+/**
+ * \dir app
+ * Main class of the application and system functions
+ */

src/app/app.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// app.h
+/**
+ * \file app/app.h
+ * \brief CApplication class
+ */
 
 #pragma once
 

src/app/main.cpp

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// main.cpp
+/**
+ * \file app/main.cpp
+ * \brief Entry point of application - main() function
+ */
 
 #include "app/app.h"
 #include "app/system.h"

src/app/system.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// system.h
+/**
+ * \file app/system.h
+ * \brief System functions: time stamps, info dialogs, etc.
+ */
 
 #pragma once
 
@@ -26,7 +29,7 @@
 /* Dialog utils */
 
 /**
- * \enum SysDialogType
+ * \enum SystemDialogType
  * \brief Type of system dialog
  */
 enum SystemDialogType
@@ -44,7 +47,7 @@ enum SystemDialogType
 };
 
 /**
- * \enum SysDialogResult
+ * \enum SystemDialogResult
  * \brief Result of system dialog
  *
  * Means which button was pressed.

src/app/system_linux.h

@@ -15,10 +15,13 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// system_linux.h
+/**
+ * \file app/system_linux.h
+ * \brief Linux-specific implementation of system functions
+ */
 
-/* This header contains Linux-specific code for system utils
-   from system.h. There is no separate .cpp module for simplicity.*/
+/* NOTE: code is contained in this header;
+ * there is no separate .cpp module for simplicity */
 
 #include <sys/time.h>
 #include <time.h>

src/app/system_other.h

@@ -15,10 +15,13 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// system_other.h
+/**
+ * \file app/system_other.h
+ * \brief Fallback code for other systems
+ */
 
-/* This header contains fallback code for other platforms for system utils
-   from system.h. There is no separate .cpp module for simplicity.*/
+/* NOTE: code is contained in this header;
+ * there is no separate .cpp module for simplicity */
 
 #include <SDL/SDL.h>
 

src/app/system_windows.h

@@ -15,10 +15,13 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// system_windows.h
+/**
+ * \file app/system_windows.h
+ * \brief Windows-specific implementation of system functions
+ */
 
-/* This header contains Windows-specific code for system utils
-   from system.h. There is no separate .cpp module for simplicity.*/
+/* NOTE: code is contained in this header;
+ * there is no separate .cpp module for simplicity */
 
 #include <windows.h>
 

src/common/README.txt

@@ -1,3 +1,4 @@
-src/common
-
-Contains headers and modules with common structs and enums.
+/**
+ * \dir common
+ * \brief Structs and utils shared throughout the application
+ */

src/common/logger.h

@@ -57,36 +57,36 @@ class CLogger : public CSingleton<CLogger>
         ~CLogger();
 
         /** Write message to console or file
-         * @param const char str - message to write
+         * @param str - message to write
          * @param ... - additional arguments
          */
         void Message(const char *str, ...);
 
         /** Write message to console or file with LOG_INFO level
-         * @param const char str - message to write
+         * @param str - message to write
          * @param ... - additional arguments
          */
         void Info(const char *str, ...);
 
         /** Write message to console or file with LOG_WARN level
-         * @param const char str - message to write
+         * @param str - message to write
          * @param ... - additional arguments
          */
         void Warn(const char *str, ...);
 
         /** Write message to console or file with LOG_ERROR level
-         * @param const char str - message to write
+         * @param str - message to write
          * @param ... - additional arguments
          */
         void Error(const char *str, ...);
 
         /** Set output file to write logs to
-         * @param std::string filename - output file to write to
+         * @param filename - output file to write to
          */
         void SetOutputFile(std::string filename);
 
         /** Set log level. Logs with level below will not be shown
-         * @param LogType level - minimum log level to write
+         * @param level - minimum log level to write
          */
         void SetLogLevel(LogType level);
 

src/graphics/README.txt

@@ -1,3 +1,12 @@
-src/graphics
+/**
+ * \dir graphics
+ * \brief Graphics engine
+ */
 
-Graphics engine
+/**
+ * \namespace Gfx
+ * \brief Namespace for (new) graphics code
+ *
+ * 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.
+ */

src/graphics/core/README.txt

@@ -1,6 +1,7 @@
-src/graphics/core
-
-Abstract core of graphics engine
-
-Core types, enums, structs and CDevice abstract class that define
-the abstract graphics device used in graphics engine
+/**
+ * \dir graphics/core
+ * \brief Abstract core of graphics engine
+ *
+ * Core types, enums, structs and CDevice abstract class that define
+ * the abstract graphics device used in graphics engine
+ */

src/graphics/core/color.h

@@ -14,7 +14,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// color.h
+/**
+ * \file graphics/core/color.h
+ * \brief Color structs and related functions
+ */
 
 #pragma once
 

src/graphics/core/device.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// device.h
+/**
+ * \file graphics/core/device.h
+ * \brief Abstract graphics device - Gfx::CDevice class and related structs/enums
+ */
 
 #pragma once
 

src/graphics/core/light.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// light.h
+/**
+ * \file graphics/core/light.h
+ * \brief Light struct and related enums
+ */
 
 #pragma once
 

src/graphics/core/material.h

@@ -14,7 +14,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// material.h
+/**
+ * \file graphics/core/material.h
+ * \brief Material struct
+ */
 
 #pragma once
 

src/graphics/core/texture.h

@@ -14,7 +14,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// texture.h
+/**
+ * \file graphics/core/texture.h
+ * \brief Texture struct and related enums
+ */
 
 #pragma once
 

src/graphics/core/vertex.h

@@ -14,7 +14,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// vertex.h
+/**
+ * \file graphics/core/vertex.h
+ * \brief Vertex structs
+ */
 
 #pragma once
 

src/graphics/d3d/README.txt

@@ -1,3 +1,4 @@
-src/graphics/d3d
-
-Possible future DirectX implementation of graphics engine
+/**
+ * \dir graphics/d3d
+ * \brief Possible future DirectX implementation of graphics engine
+ */

src/graphics/engine/README.txt

@@ -1,8 +1,9 @@
-src/graphics/engine
-
-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
+/**
+ * \dir 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
+ */

src/graphics/engine/camera.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// camera.h
+/**
+ * \file graphics/engine/camera.h
+ * \brief Camera handling - Gfx::CCamera class
+ */
 
 #pragma once
 

src/graphics/engine/cloud.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// cloud.h
+/**
+ * \file graphics/engine/cloud.h
+ * \brief Cloud rendering - Gfx::CCloud class
+ */
 
 #pragma once
 

src/graphics/engine/engine.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// engine.h
+/**
+ * \file graphics/engine/engine.h
+ * \brief Main graphics engine - Gfx::CEngine class
+ */
 
 #pragma once
 

src/graphics/engine/lightman.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// lightman.h
+/**
+ * \file graphics/engine/lightman.h
+ * \brief Dynamic light manager - Gfx::CLightManager class
+ */
 
 #pragma once
 

src/graphics/engine/lightning.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// lightning.h (aka blitz.h)
+/**
+ * \file graphics/engine/lightning.h
+ * \brief Lightning rendering - Gfx::CLightning class (aka blitz)
+ */
 
 #pragma once
 

src/graphics/engine/modelfile.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// modelfile.h (aka modfile.h)
+/**
+ * \file graphics/engine/modelfile.h
+ * \brief Model loading - Gfx::CModelFile class (aka modfile)
+ */
 
 #include "graphics/engine/engine.h"
 #include "graphics/core/vertex.h"

src/graphics/engine/particle.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// particle.h (aka particule.h)
+/**
+ * \file graphics/engine/particle.h
+ * \brief Particle rendering - Gfx::CParticle class (aka particule)
+ */
 
 #pragma once
 

src/graphics/engine/planet.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// planet.h
+/**
+ * \file graphics/engine/planet.h
+ * \brief Planet rendering - Gfx::CPlanet class
+ */
 
 #pragma once
 

src/graphics/engine/pyro.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// pyro.h
+/**
+ * \file graphics/engine/pyro.h
+ * \brief Fire effect rendering - Gfx::CPyro class
+ */
 
 #pragma once
 

src/graphics/engine/terrain.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// terrain.h
+/**
+ * \file graphics/engine/terrain.h
+ * \brief Terrain rendering - Gfx::CTerrain class
+ */
 
 #pragma once
 

src/graphics/engine/text.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// text.h
+/**
+ * \file graphics/engine/text.h
+ * \brief Text rendering - Gfx::CText class
+ */
 
 #pragma once
 

src/graphics/engine/water.h

@@ -15,7 +15,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// water.h
+/**
+ * \file graphics/engine/water.h
+ * \brief Water rendering - Gfx::CWater class
+ */
 
 #pragma once
 

src/graphics/opengl/README.txt

@@ -1,6 +1,7 @@
-src/graphics/opengl
-
-OpenGL engine implementation
-
-Contains the concrete implementation using OpenGL of abstract CDevice class
-from src/graphics/core
+/**
+ * \dir graphics/opengl
+ * \brief OpenGL engine implementation
+ *
+ * Contains the concrete implementation using OpenGL of abstract CDevice class
+ * from src/graphics/core
+ */

src/graphics/opengl/gldevice.h

@@ -14,7 +14,10 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-// gldevice.h
+/**
+ * \file graphics/opengl/gldevice.h
+ * \brief OpenGL implementation - Gfx::CGLDevice class
+ */
 
 #pragma once
 

src/math/README.txt

@@ -1,3 +1,12 @@
-src/math
+/**
+ * \dir math
+ * \brief Common mathematical structures and functions
+ */
 
-Contains common mathematical structures and functions.
+/**
+ * \namespace Math
+ * \brief Namespace for (new) math code
+ *
+ * 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.
+ */

src/math/all.h

@@ -14,14 +14,13 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-/** @defgroup MathAllModule math/all.h
-   Includes all other math module headers.
+/**
+ * \file math/all.h
+ * \brief Includes all other math module headers
  */
 
 #pragma once
 
-/* @{ */ // start of group
-
 #include "const.h"
 #include "func.h"
 #include "point.h"
@@ -30,5 +29,3 @@
 #include "geometry.h"
 
 #include "conv.h"
-
-/* @} */ // end of group

src/math/const.h

@@ -14,8 +14,9 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-/** @defgroup MathConstModule math/const.h
-   Contains the math constants used in math functions.
+/**
+ * \file math/const.h
+ * \brief Constants used in math functions
  */
 
 #pragma once
@@ -26,7 +27,6 @@
 // Math module namespace
 namespace Math
 {
-/* @{ */ // start of group
 
 //! Tolerance level -- minimum accepted float value
 const float TOLERANCE = 1e-6f;
@@ -50,6 +50,5 @@ const float RAD_TO_DEG = 57.29577951308232286465f;
 //! Natural logarithm of 2
 const float LOG_2 = log(2.0f);
 
-/* @} */ // end of group
 }; // namespace Math
 

src/math/func.h

@@ -15,8 +15,9 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-/** @defgroup MathFuncModule math/func.h
-     Contains common math functions.
+/**
+ * \file math/func.h
+ * \brief Common math functions
  */
 
 #pragma once
@@ -31,8 +32,6 @@
 namespace Math
 {
 
-/* @{ */ // start of group
-
 //! Compares \a a and \a b within \a tolerance
 inline bool IsEqual(float a, float b, float tolerance = Math::TOLERANCE)
 {
@@ -188,11 +187,13 @@ inline float Direction(float a, float g)
 
 //! Managing the dead zone of a joystick.
 /**
-\verbatimin:   -1            0            1
+\verbatim
+in:   -1            0            1
 --|-------|----o----|-------|-->
              <---->
               dead
-out:  -1       0         0       1\endverbatim */
+out:  -1       0         0       1
+\endverbatim */
 inline float Neutral(float value, float dead)
 {
     if ( fabs(value) <= dead )
@@ -226,7 +227,8 @@ inline float Smooth(float actual, float hope, float time)
 
 //! Bounces any movement
 /**
-\verbatimout
+\verbatim
+out
  |
 1+------o-------o---
  |    o | o   o |  | bounce
@@ -235,7 +237,8 @@ inline float Smooth(float actual, float hope, float time)
  | o    |       |
 -o------|-------+----> progress
 0|      |       1
- |<---->|middle\endverbatim */
+ |<---->|middle
+\endverbatim */
 inline float Bounce(float progress, float middle = 0.3f, float bounce = 0.4f)
 {
     if ( progress < middle )
@@ -250,6 +253,4 @@ inline float Bounce(float progress, float middle = 0.3f, float bounce = 0.4f)
     }
 }
 
-/* @} */ // end of group
-
 }; // namespace Math

src/math/geometry.h

@@ -15,9 +15,9 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-/** @defgroup MathGeometryModule math/geometry.h
-   Contains math functions related to 3D geometry calculations,
-   transformations, etc.
+/**
+ * \file math/geometry.h
+ * \brief Math functions related to 3D geometry calculations, transformations, etc.
  */
 
 #pragma once
@@ -36,9 +36,6 @@
 namespace Math
 {
 
-/* @{ */ // start of group
-
-
 //! Returns py up on the line \a a - \a b
 inline float MidPoint(const Math::Point &a, const Math::Point &b, float px)
 {
@@ -566,6 +563,4 @@ inline Math::Vector RotateView(Math::Vector center, float angleH, float angleV,
     return eye+center;
 }
 
-/* @} */ // end of group
-
 }; // namespace Math

src/math/intpoint.h

@@ -14,18 +14,18 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-/** @defgroup MathIntPointModule math/intpoint.h
-   Contains the IntPoint struct.
+/**
+ * \file math/intpoint.h
+ * \brief IntPoint struct
  */
 
 #pragma once
 
 namespace Math {
 
-/* @{ */ // start of group
-
 /**
- * \struct IntPoint 2D Point with integer coords
+ * \struct IntPoint
+ * \brief 2D Point with integer coords
  *
  * Analog of WinAPI's POINT struct.
  */
@@ -39,6 +39,4 @@ struct IntPoint
     IntPoint(int aX = 0, int aY = 0) : x(aX), y(aY) {}
 };
 
-/* @} */ // end of group
-
 }; // namespace Math

src/math/matrix.h

@@ -14,8 +14,9 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-/** @defgroup MathMatrixModule math/matrix.h
-   Contains the Matrix struct and related functions.
+/**
+ * \file math/matrix.h
+ * \brief Matrix struct and related functions
  */
 
 #pragma once
@@ -32,8 +33,6 @@
 namespace Math
 {
 
-/* @{ */ // start of group
-
 /** \struct Matrix math/matrix.h
     \brief 4x4 matrix
 
@@ -42,11 +41,12 @@ namespace Math
 
     The internal representation is a 16-value table in column-major order, thus:
 
-    \verbatim
+\verbatim
 m[0 ] m[4 ] m[8 ] m[12]
 m[1 ] m[5 ] m[9 ] m[13]
 m[2 ] m[6 ] m[10] m[14]
-m[3 ] m[7 ] m[11] m[15] \endverbatim
+m[3 ] m[7 ] m[11] m[15]
+\endverbatim
 
     This representation is native to OpenGL; DirectX requires transposing the matrix.
 
@@ -405,11 +405,15 @@ inline Math::Matrix MultiplyMatrices(const Math::Matrix &left, const Math::Matri
 }
 
 //! Calculates the result of multiplying m * v
-/** The multiplication is performed thus:
-\verbatim [  m.m[0 ] m.m[4 ] m.m[8 ] m.m[12]  ]   [ v.x ]
+/**
+    The multiplication is performed thus:
+
+\verbatim
+[  m.m[0 ] m.m[4 ] m.m[8 ] m.m[12]  ]   [ v.x ]
 [  m.m[1 ] m.m[5 ] m.m[9 ] m.m[13]  ]   [ v.y ]
 [  m.m[2 ] m.m[6 ] m.m[10] m.m[14]  ] * [ v.z ]
-[  m.m[3 ] m.m[7 ] m.m[11] m.m[15]  ]   [  1  ] \endverbatim
+[  m.m[3 ] m.m[7 ] m.m[11] m.m[15]  ]   [  1  ]
+\endverbatim
 
    The result, a 4x1 vector is then converted to 3x1 by dividing
    x,y,z coords by the fourth coord (w). */
@@ -434,6 +438,4 @@ inline Math::Vector MatrixVectorMultiply(const Math::Matrix &m, const Math::Vect
     return Math::Vector(x, y, z);
 }
 
-/* @} */ // end of group
-
 }; // namespace Math

src/math/point.h

@@ -14,8 +14,9 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see    http://www.gnu.org/licenses/.
 
-/** @defgroup MathPointModule math/point.h
-     Contains the Point struct and related functions.
+/**
+ * \file math/point.h
+ * \brief Point struct and related functions
  */
 
 #pragma once
@@ -31,8 +32,6 @@
 namespace Math
 {
 
-/* @{ */ // start of group
-
 /** \struct Point math/point.h
     \brief 2D point
 
@@ -188,6 +187,4 @@ inline float Distance(const Point &a, const Point &b)
     return sqrtf((a.x-b.x)*(a.x-b.x) + (a.y-b.y)*(a.y-b.y));
 }
 
-/* @} */ // end of group
-
 }; // namespace Math

src/math/vector.h

@@ -14,8 +14,9 @@
 // * You should have received a copy of the GNU General Public License
 // * along with this program. If not, see  http://www.gnu.org/licenses/.
 
-/** @defgroup MathVectorModule math/vector.h
-   Contains the Vector struct and related functions.
+/**
+ * \file math/vector.h
+ * \brief Vector struct and related functions
  */
 
 #pragma once
@@ -31,8 +32,6 @@
 namespace Math
 {
 
-/* @{ */ // start of group
-
 /** \struct Vector math/vector.h
     \brief 3D (3x1) vector
 
@@ -263,6 +262,4 @@ inline float Distance(const Math::Vector &a, const Math::Vector &b)
                   (a.z-b.z)*(a.z-b.z) );
 }
 
-/* @} */ // end of group
-
 }; // namespace Math

src/object/README.txt

@@ -1,3 +1,7 @@
-src/object
-
-Contains modules of robots and buildings.
+/**
+ * \dir 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.
+ */

src/physics/README.txt

@@ -1,3 +1,4 @@
-src/physics
-
-Contains the physics module.
+/**
+ * \dir physics
+ * \brief Physics engine
+ */

src/sound/README.txt

@@ -1,3 +1,4 @@
-src/sound
-
-Contains the sound module - for playing sounds and music.
+/**
+ * \dir sound
+ * \brief Sound module - playing sounds and music
+ */

src/ui/README.txt

@@ -1,3 +1,4 @@
-src/ui
-
-Contains modules responsible for displaying the user interface controls (from game menus and HUD).
+/**
+ * \dir ui
+ * \brief 2D user interface controls
+ */