More work to enhance Doxygen output

git-svn-id: svn+ssh://svn.code.sf.net/p/supertuxkart/code/main/trunk@5250 178a84e3-b1eb-0310-8ba1-8eac791a3b58

src/ide/Xcode/STK_XCode.xcodeproj/project.pbxproj

@@ -1916,12 +1916,12 @@
 				956830DE1132EC9E00088D14 /* irr_debug_drawer.cpp */,
 				956830DF1132EC9E00088D14 /* irr_debug_drawer.hpp */,
 				95C2B1840F296545000D3E5D /* kart_motion_state.hpp */,
-				95CA59F60F82FCB7003323DB /* physical_object.hpp */,
 				95CA59F70F82FCB7003323DB /* physical_object.cpp */,
+				95CA59F60F82FCB7003323DB /* physical_object.hpp */,
 				95C2B1870F296545000D3E5D /* physics.cpp */,
 				95C2B1880F296545000D3E5D /* physics.hpp */,
-				953EAAB00F30A4410000D57D /* triangle_mesh.hpp */,
 				953EAAB10F30A4410000D57D /* triangle_mesh.cpp */,
+				953EAAB00F30A4410000D57D /* triangle_mesh.hpp */,
 			);
 			name = physics;
 			path = ../../physics;

src/modes/follow_the_leader.hpp

@@ -21,6 +21,10 @@
 #include "modes/linear_world.hpp"
 #include "states_screens/race_gui.hpp"
 
+/**
+  * \brief An implementation of World, based on LinearWorld, to provide the Follow-the-leader game mode
+  * \ingroup modes
+  */
 class FollowTheLeaderRace : public LinearWorld
 {
 private:

src/modes/linear_world.hpp

@@ -26,6 +26,7 @@
  * A 'linear world' is a subcategory of world used in 'standard' races, i.e.
  * with a start line and a road that loops. This includes management of drivelines
  * and lap counting.
+ * \ingroup modes
  */
 class LinearWorld : public World
 {

src/modes/profile_world.hpp

@@ -24,6 +24,10 @@
 
 class Kart;
 
+/**
+ * \brief An implementation of World, used for profiling only
+ * \ingroup modes
+ */
 class ProfileWorld : public StandardRace
 {
 private:

src/modes/standard_race.hpp

@@ -21,8 +21,9 @@
 #include "modes/linear_world.hpp"
 
 /**
-  * Represents a standard race, i.e. with a start, end and laps.
+  * \brief Represents a standard race, i.e. with a start, end and laps.
   * Used in Grand Prix, Quick Race and Time Trial.
+  * \ingroup modes
   */
 class StandardRace : public LinearWorld
 {

src/modes/three_strikes_battle.hpp

@@ -25,7 +25,10 @@
 #include "modes/world.hpp"
 #include "states_screens/race_gui.hpp"
 
-
+/**
+ * \brief An implementation of World, to provide the 3 strikes battle game mode
+ * \ingroup modes
+ */
 class ThreeStrikesBattle : public World
 {
 private:

src/modes/world.hpp

@@ -20,6 +20,8 @@
 #ifndef HEADER_WORLD_HPP
 #define HEADER_WORLD_HPP
 
+/** \defgroup modes */
+
 #include <vector>
 
 #include "modes/world_status.hpp"
@@ -34,7 +36,9 @@ class Kart;
 class SFXBase;
 class Track;
 
-/** This class is responsible for running the actual race. A world is created
+/** 
+ *  \brief base class for all game modes
+ *  This class is responsible for running the actual race. A world is created
  *  by the race manager on the start of each race (so a new world is created
  *  for each race of a Grand Prix). It creates the 
  *  physics, loads the track, creates all karts, and initialises the race
@@ -72,6 +76,7 @@ class Track;
  *        creating a special kart type (see RaceManager::KartType), scoring
  *        would be done in the mode specific world (instead of in the
  *        RaceManager).
+ * \ingroup modes
  */
 
 class World : public WorldStatus

src/modes/world_status.hpp

@@ -21,8 +21,9 @@
 class SFXBase;
 
 /**
- * A class that manages the clock (countdown, chrono, etc.) Also manages stuff
- * like the 'ready/set/go' text at the beginning or the delay at the end of a race.
+ * \brief A class that manages the clock (countdown, chrono, etc.)
+ * Also manages stuff like the 'ready/set/go' text at the beginning or the delay at the end of a race.
+ * \ingroup modes
  */
 class WorldStatus
 {

src/physics/btKart.hpp

@@ -15,9 +15,11 @@
 
 class btDynamicsWorld;
 struct btWheelInfo;
+
 /** The btKart is a raycast vehicle, that does not skid. It therefore solves
  *  the problems with the plain bullet physics that karts would often rotate
  *  on a spot if one of the wheels loses contact with the ground.
+ * \ingroup physics
  */
 class btKart : public btRaycastVehicle
 {

src/physics/btUprightConstraint.hpp

@@ -24,7 +24,9 @@ subject to the following restrictions:
 class btRigidBody;
 class Kart;
 
-
+/**
+  * \ingroup physics
+  */
 class btUprightConstraint : public btTypedConstraint
 {
 private:

src/physics/irr_debug_drawer.hpp

@@ -28,6 +28,9 @@ using namespace irr;
 #include "graphics/irr_driver.hpp"
 #include "utils/vec3.hpp"
 
+/**
+  * \ingroup physics
+  */
 class IrrDebugDrawer : public btIDebugDraw
 {
     /** The drawing mode to use: 

src/physics/kart_motion_state.hpp

@@ -25,6 +25,7 @@
 /** This is a very simple motion state implementation for bullet, which does
  *  not support any transformation from physics transform to graphics 
  *  transform. 
+ * \ingroup physics
  */
 
 class KartMotionState : public btMotionState

src/physics/physical_object.hpp

@@ -30,6 +30,9 @@
 
 class XMLNode;
 
+/**
+  * \ingroup physics
+  */
 class PhysicalObject : public TrackObject
 {
 public:

src/physics/physics.hpp

@@ -20,6 +20,8 @@
 #ifndef HEADER_PHYSICS_HPP
 #define HEADER_PHYSICS_HPP
 
+/** \defgroup physics */
+
 #include <set>
 #include <vector>
 
@@ -31,6 +33,9 @@
 class Vec3;
 class Kart;
 
+/**
+  * \ingroup physics
+  */
 class Physics : public btSequentialImpulseConstraintSolver
 {
 private:

src/physics/triangle_mesh.hpp

@@ -27,8 +27,9 @@
 
 class Material;
 
-/** A special class to store a triangle mesh with a separate material
- *  per triangle.
+/** 
+ * \brief A special class to store a triangle mesh with a separate material per triangle.
+ * \ingroup physics
  */
 class TriangleMesh
 {

src/race/grand_prix_data.hpp

@@ -28,7 +28,9 @@
 #include <stdexcept>
 
 /** Simple class that hold the data relevant to a 'grand_prix', aka. a number
-    of races that has to be completed one after the other */
+  * of races that has to be completed one after the other
+  * \ingroup race
+  */
 class GrandPrixData
 {
     irr::core::stringw m_name;         //!< The name of the grand prix - might be translated!

src/race/grand_prix_manager.hpp

@@ -25,6 +25,9 @@
 
 #include "race/grand_prix_data.hpp"
 
+/**
+  * \ingroup race
+  */
 class GrandPrixManager
 {
 private:

src/race/highscore_manager.hpp

@@ -27,9 +27,10 @@
 #include "race/highscores.hpp"
 
 /**
-  * This class reads and writes the 'highscores.data' file, and also takes
+  * This class reads and writes the 'highscores.xml' file, and also takes
   * care of dealing with new records. One 'HighscoreEntry' object is created
   * for each highscore entry.
+  * \ingroup race
   */
 class HighscoreManager
 {

src/race/highscores.hpp

@@ -31,6 +31,7 @@ class XMLNode;
 /**
  *  Represents one highscore entry, i.e. the (atm up to three) highscores
  *  for a particular setting (track, #karts, difficulty etc).
+ * \ingroup race
  */
 class Highscores
 {

src/race/history.hpp

@@ -29,6 +29,9 @@
 
 class Kart;
 
+/**
+  * \ingroup race
+  */
 class History
 {
 public:

src/race/race_manager.hpp

@@ -20,6 +20,8 @@
 #ifndef HEADER_RACEMANAGER_HPP
 #define HEADER_RACEMANAGER_HPP
 
+/** \defgroup race */
+
 #include <vector>
 #include <algorithm>
 #include <string>
@@ -38,7 +40,8 @@ static const char* IDENT_TTRIAL  = "STD_TIMETRIAL";
 static const char* FTL_IDENT     = "FOLLOW_LEADER";
 static const char* STRIKES_IDENT = "BATTLE_3_STRIKES";
 
-/** The race manager has two functions:
+/** 
+ * The race manager has two functions:
  *  1) it stores information about the race the user selected (e.g. number
  *     of karts, track, race mode etc.). Most of the values are just stored
  *     from the menus, and just read back, except for GP mode (the race
@@ -67,6 +70,8 @@ static const char* STRIKES_IDENT = "BATTLE_3_STRIKES";
  *  The race manager handles all race types as a kind of grand prix. E.g.:
  *  a quick race is basically a GP with only one track (so the race manager
  *  keeps track of scores even though no scores are used in a quick race).
+ *
+ * \ingroup race
  */
 class RaceManager
 {

src/states_screens/arenas_screen.hpp

@@ -23,6 +23,10 @@
 
 namespace GUIEngine { class Widget; }
 
+/**
+  * \brief Handles the screen where a battle arena choice is offered
+  * \ingroup states_screens
+  */
 class ArenasScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<ArenasScreen>
 {
     friend class GUIEngine::ScreenSingleton<ArenasScreen>;

src/states_screens/challenges.hpp

@@ -23,21 +23,23 @@
 #include "guiengine/screen.hpp"
 #include "utils/ptr_vector.hpp"
 
-namespace GUIEngine
+ 
+/**
+  * \brief Handles the screen where the player is shown active and solved challenges
+  * \ingroup states_screens
+  */
+class ChallengesScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<ChallengesScreen>
 {
+    friend class GUIEngine::ScreenSingleton<ChallengesScreen>;
+    ChallengesScreen();
     
-    class ChallengesScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<ChallengesScreen>
-    {
-        friend class GUIEngine::ScreenSingleton<ChallengesScreen>;
-        ChallengesScreen();
-        
-    public:
+public:
+
+    void onUpdate(float dt, irr::video::IVideoDriver*);
+    
+    void init();
+    void tearDown();
+    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+};
 
-        void onUpdate(float dt, irr::video::IVideoDriver*);
-        
-        void init();
-        void tearDown();
-        void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
-    };
-}
 #endif

src/states_screens/credits.cpp

@@ -32,307 +32,304 @@ using irr::core::stringc;
 DEFINE_SCREEN_SINGLETON( GUIEngine::CreditsScreen );
 
 
-namespace GUIEngine
+const float TIME_SECTION_FADE = 0.8f;
+const float ENTRIES_FADE_TIME = 0.3f;
+
+class CreditsEntry
 {
-    const float TIME_SECTION_FADE = 0.8f;
-    const float ENTRIES_FADE_TIME = 0.3f;
-
-    class CreditsEntry
-    {
-    public:
-        stringw m_name;
-        std::vector<stringw> m_subentries;
-        
-        CreditsEntry(stringw& name)
-        {
-            m_name = name;
-        }
-    };
+public:
+    stringw m_name;
+    std::vector<stringw> m_subentries;
     
-    
-    class CreditsSection
+    CreditsEntry(stringw& name)
     {
-    public:
-        // read-only
-        std::vector<CreditsEntry> m_entries;
-        stringw m_name;
-        
-        CreditsSection(stringw name)
-        {
-            this->m_name = name;
-        }
-        void addEntry(CreditsEntry& entry)
-        {
-            m_entries.push_back(entry);
-        }
-        void addSubEntry(stringw& subEntryString)
-        {
-            m_entries[m_entries.size()-1].m_subentries.push_back(subEntryString);
-        }
-    };
-    
-    CreditsSection* CreditsScreen::getCurrentSection()
-    {
-        return m_sections.get(m_sections.size()-1);
+        m_name = name;
     }
-    
-    bool getWideLine(std::ifstream& file, stringw* out)
-    {
-        if (!file.good())
-        {
-            //std::cout << "File is not good!\n";
-            return false;
-        }
-        wchar_t wide_char;
+};
 
-        bool found_eol = false;
-        stringw line;
-        
-        char buff[2];
-        
-        while (true)
+
+class CreditsSection
+{
+public:
+    // read-only
+    std::vector<CreditsEntry> m_entries;
+    stringw m_name;
+    
+    CreditsSection(stringw name)
+    {
+        this->m_name = name;
+    }
+    void addEntry(CreditsEntry& entry)
+    {
+        m_entries.push_back(entry);
+    }
+    void addSubEntry(stringw& subEntryString)
+    {
+        m_entries[m_entries.size()-1].m_subentries.push_back(subEntryString);
+    }
+};
+
+CreditsSection* CreditsScreen::getCurrentSection()
+{
+    return m_sections.get(m_sections.size()-1);
+}
+
+bool getWideLine(std::ifstream& file, stringw* out)
+{
+    if (!file.good())
+    {
+        //std::cout << "File is not good!\n";
+        return false;
+    }
+    wchar_t wide_char;
+    
+    bool found_eol = false;
+    stringw line;
+    
+    char buff[2];
+    
+    while (true)
+    {
+        file.read( buff, 2 );
+        if (file.good())
         {
-            file.read( buff, 2 );
-            if (file.good())
+            //std::cout << buff[0] << ", " << buff[1]
+            //          << "(" << std::hex << (unsigned)buff[0] << ", " << std::hex << (unsigned)buff[1] << ")\n";
+            
+            // FIXME: endianness issues possible here?
+            wide_char = unsigned(buff[0] & 0xFF) | (unsigned(buff[1] & 0xFF) << 8);
+            line += wide_char;
+            //std::cout << "Read char " << (char)(wide_char) << " (" << std::hex << wide_char << ")" << std::endl;
+            if (wide_char == L'\n')
             {
-                //std::cout << buff[0] << ", " << buff[1]
-                //          << "(" << std::hex << (unsigned)buff[0] << ", " << std::hex << (unsigned)buff[1] << ")\n";
-                
-                // FIXME: endianness issues possible here?
-                wide_char = unsigned(buff[0] & 0xFF) | (unsigned(buff[1] & 0xFF) << 8);
-                line += wide_char;
-                //std::cout << "Read char " << (char)(wide_char) << " (" << std::hex << wide_char << ")" << std::endl;
-                if (wide_char == L'\n')
-                {
-                    //std::cout << "EOL\n";
-                    found_eol = true;
-                    break;
-                }
-            }
-            else
-            {
-                //std::cout << "- file not good -\n";
-                //file.get(); // if we stopped on EOL, try to skip it
+                //std::cout << "EOL\n";
+                found_eol = true;
                 break;
             }
         }
-        
-        if (!found_eol) return false;
-        *out = line;
-        //std::cout << "Read line <" << stringc(line.c_str()).c_str() << ">\n";
-        return true;
+        else
+        {
+            //std::cout << "- file not good -\n";
+            //file.get(); // if we stopped on EOL, try to skip it
+            break;
+        }
     }
     
-    CreditsScreen::CreditsScreen() : Screen("credits.stkgui")
-    {
-        reset();
-        
-        throttleFPS = false;
-        
-        std::string creditsfile = file_manager->getDataDir() + "/CREDITS";
+    if (!found_eol) return false;
+    *out = line;
+    //std::cout << "Read line <" << stringc(line.c_str()).c_str() << ">\n";
+    return true;
+}
 
-        std::ifstream file( creditsfile.c_str() ) ;
-        stringw line;
+CreditsScreen::CreditsScreen() : Screen("credits.stkgui")
+{
+    reset();
+    
+    throttleFPS = false;
+    
+    std::string creditsfile = file_manager->getDataDir() + "/CREDITS";
+    
+    std::ifstream file( creditsfile.c_str() ) ;
+    stringw line;
+    
+    // skip Unicode header
+    file.get();
+    file.get();
+    
+    // let's assume the file is encoded as UTF-16
+    while (getWideLine( file, &line ))
+    {
+        line = line.trim();
         
-        // skip Unicode header
-        file.get();
-        file.get();
+        if (line.size() < 1) continue; // empty line
         
-        // let's assume the file is encoded as UTF-16
-        while (getWideLine( file, &line ))
+        if ((line[0] & 0xFF) == '=' && (line[line.size()-1] & 0xFF) == '=')
         {
+            line = stringw( line.subString(1, line.size()-2).c_str() );
             line = line.trim();
             
-            if (line.size() < 1) continue; // empty line
-            
-            if ((line[0] & 0xFF) == '=' && (line[line.size()-1] & 0xFF) == '=')
-            {
-                line = stringw( line.subString(1, line.size()-2).c_str() );
-                line = line.trim();
-                
-                //stringc cversion = line.c_str();
-                //std::cout << "Section : " << (char*)(cversion.c_str()) << std::endl;
-                m_sections.push_back( new CreditsSection(line)  );
-            }
-            else if ((line[0] & 0xFF) == '-')
-            {
-                line = stringw( line.subString(1, line.size()-1).c_str() );
-                //line = line.trim();
-                
-                //stringc cversion = line.c_str();
-                //std::cout << "---- Sub-Entry : " << (char*)(cversion.c_str()) << std::endl;
-                
-                getCurrentSection()->addSubEntry( line );
-            }
-            else
-            {
-                //tringc cversion = line.c_str();
-                //std::cout << "-- Entry : " << (char*)(cversion.c_str()) << std::endl;
-                
-                CreditsEntry entry(line);
-                getCurrentSection()->addEntry( entry );
-            }
-        } // end while
-        assert(m_sections.size() > 0);
-        
-    }
-    
-    void CreditsScreen::setArea(const int x, const int y, const int w, const int h)
-    {
-        this->x = x;
-        this->y = y;
-        this->w = w;
-        this->h = h;
-        
-        m_section_rect = core::rect< s32 >( x, y, x+w, y+h/6 );
-    }
-
-    void CreditsScreen::reset()
-    {
-        m_curr_section = 0;
-        m_curr_element = -1;
-        time_before_next_step = TIME_SECTION_FADE;
-        m_time_element = 2.5f;
-    }
-    
-    void CreditsScreen::onUpdate(float elapsed_time, irr::video::IVideoDriver*)
-    {
-        time_before_next_step -= elapsed_time*0.8f; // multiply by 0.8 to slow it down a bit as a whole
-
-        const bool before_first_elem = (m_curr_element == -1);
-        const bool after_last_elem   = (m_curr_element >= (int)m_sections[m_curr_section].m_entries.size());
-
-        
-        // ---- section name
-        video::SColor color( 255 /* a */, 0 /* r */, 0 /* g */ , 75 /* b */ );
-        video::SColor white_color( 255, 255, 255, 255 );
-
-        // manage fade-in
-        if (before_first_elem)
+            //stringc cversion = line.c_str();
+            //std::cout << "Section : " << (char*)(cversion.c_str()) << std::endl;
+            m_sections.push_back( new CreditsSection(line)  );
+        }
+        else if ((line[0] & 0xFF) == '-')
         {
-            // I use 425 instead of 255 so that there is a little pause after
-            int alpha = 425 - (int)(time_before_next_step/TIME_SECTION_FADE * 425);
+            line = stringw( line.subString(1, line.size()-1).c_str() );
+            //line = line.trim();
+            
+            //stringc cversion = line.c_str();
+            //std::cout << "---- Sub-Entry : " << (char*)(cversion.c_str()) << std::endl;
+            
+            getCurrentSection()->addSubEntry( line );
+        }
+        else
+        {
+            //tringc cversion = line.c_str();
+            //std::cout << "-- Entry : " << (char*)(cversion.c_str()) << std::endl;
+            
+            CreditsEntry entry(line);
+            getCurrentSection()->addEntry( entry );
+        }
+    } // end while
+    assert(m_sections.size() > 0);
+    
+}
+
+void CreditsScreen::setArea(const int x, const int y, const int w, const int h)
+{
+    this->x = x;
+    this->y = y;
+    this->w = w;
+    this->h = h;
+    
+    m_section_rect = core::rect< s32 >( x, y, x+w, y+h/6 );
+}
+
+void CreditsScreen::reset()
+{
+    m_curr_section = 0;
+    m_curr_element = -1;
+    time_before_next_step = TIME_SECTION_FADE;
+    m_time_element = 2.5f;
+}
+
+void CreditsScreen::onUpdate(float elapsed_time, irr::video::IVideoDriver*)
+{
+    time_before_next_step -= elapsed_time*0.8f; // multiply by 0.8 to slow it down a bit as a whole
+    
+    const bool before_first_elem = (m_curr_element == -1);
+    const bool after_last_elem   = (m_curr_element >= (int)m_sections[m_curr_section].m_entries.size());
+    
+    
+    // ---- section name
+    video::SColor color( 255 /* a */, 0 /* r */, 0 /* g */ , 75 /* b */ );
+    video::SColor white_color( 255, 255, 255, 255 );
+    
+    // manage fade-in
+    if (before_first_elem)
+    {
+        // I use 425 instead of 255 so that there is a little pause after
+        int alpha = 425 - (int)(time_before_next_step/TIME_SECTION_FADE * 425);
+        if      (alpha < 0) alpha = 0;
+        else if (alpha > 255) alpha = 255;
+        white_color.setAlpha( alpha );
+    }
+    // manage fade-out
+    else if (after_last_elem)
+    {
+        // I use 425 instead of 255 so that there is a little pause after
+        int alpha = (int)(time_before_next_step/TIME_SECTION_FADE * 425) - (425-255);
+        if      (alpha < 0)   alpha = 0;
+        else if (alpha > 255) alpha = 255;
+        white_color.setAlpha( alpha );
+    }
+    
+    GUIEngine::getTitleFont()->draw(m_sections[m_curr_section].m_name.c_str(), m_section_rect, white_color,
+                                    true /* center h */, true /* center v */ );
+    
+    // draw entries
+    if (!before_first_elem && !after_last_elem)
+    {
+        int text_offset  = 0;
+        
+        // fade in
+        if (time_before_next_step < ENTRIES_FADE_TIME)
+        {
+            const float fade_in = time_before_next_step / ENTRIES_FADE_TIME;
+            
+            int alpha =  (int)(fade_in * 255);
+            
             if      (alpha < 0) alpha = 0;
             else if (alpha > 255) alpha = 255;
-            white_color.setAlpha( alpha );
+            
+            color.setAlpha( alpha );
+            
+            text_offset = (int)((1.0f - fade_in) * 100);
         }
-        // manage fade-out
-        else if (after_last_elem)
+        // fade out
+        else if (time_before_next_step >= m_time_element - ENTRIES_FADE_TIME)
         {
-            // I use 425 instead of 255 so that there is a little pause after
-            int alpha = (int)(time_before_next_step/TIME_SECTION_FADE * 425) - (425-255);
-            if      (alpha < 0)   alpha = 0;
-            else if (alpha > 255) alpha = 255;
-            white_color.setAlpha( alpha );
+            const float fade_out = (time_before_next_step - (m_time_element - ENTRIES_FADE_TIME)) / ENTRIES_FADE_TIME;
+            
+            int alpha = 255 - (int)(fade_out * 255);
+            if(alpha < 0) alpha = 0;
+            else if(alpha > 255) alpha = 255;
+            color.setAlpha( alpha );
+            
+            text_offset = -(int)(fade_out * 100);
         }
         
-        GUIEngine::getTitleFont()->draw(m_sections[m_curr_section].m_name.c_str(), m_section_rect, white_color,
-                                   true /* center h */, true /* center v */ );
         
-        // draw entries
-        if (!before_first_elem && !after_last_elem)
+        GUIEngine::getFont()->draw(m_sections[m_curr_section].m_entries[m_curr_element].m_name.c_str(),
+                                   core::rect< s32 >( x + text_offset, y+h/6, x+w+text_offset, y+h/3 ), color,
+                                   false /* center h */, true /* center v */ );
+        
+        const int subamount = m_sections[m_curr_section].m_entries[m_curr_element].m_subentries.size();
+        int suby = y+h/3;
+        const int inc = subamount == 0 ? h/8 : std::min(h/8, (h - h/3)/(subamount+1));
+        for(int i=0; i<subamount; i++)
         {
-            int text_offset  = 0;
-            
-            // fade in
-            if (time_before_next_step < ENTRIES_FADE_TIME)
-            {
-                const float fade_in = time_before_next_step / ENTRIES_FADE_TIME;
-                
-                int alpha =  (int)(fade_in * 255);
-                
-                if      (alpha < 0) alpha = 0;
-                else if (alpha > 255) alpha = 255;
-                
-                color.setAlpha( alpha );
-                
-                text_offset = (int)((1.0f - fade_in) * 100);
-            }
-            // fade out
-            else if (time_before_next_step >= m_time_element - ENTRIES_FADE_TIME)
-            {
-                const float fade_out = (time_before_next_step - (m_time_element - ENTRIES_FADE_TIME)) / ENTRIES_FADE_TIME;
-                
-                int alpha = 255 - (int)(fade_out * 255);
-                if(alpha < 0) alpha = 0;
-                else if(alpha > 255) alpha = 255;
-                color.setAlpha( alpha );
-                
-                text_offset = -(int)(fade_out * 100);
-            }
-            
-            
-            GUIEngine::getFont()->draw(m_sections[m_curr_section].m_entries[m_curr_element].m_name.c_str(),
-                                       core::rect< s32 >( x + text_offset, y+h/6, x+w+text_offset, y+h/3 ), color,
-                                       false /* center h */, true /* center v */ );
-            
-            const int subamount = m_sections[m_curr_section].m_entries[m_curr_element].m_subentries.size();
-            int suby = y+h/3;
-            const int inc = subamount == 0 ? h/8 : std::min(h/8, (h - h/3)/(subamount+1));
-            for(int i=0; i<subamount; i++)
-            {
-               GUIEngine::getFont()->draw(m_sections[m_curr_section].m_entries[m_curr_element].m_subentries[i].c_str(),
-                                          core::rect< s32 >( x + 32, suby + text_offset/(1+1), x+w+32, suby+h/8 + text_offset/(1+1) ),
-                                          color,
-                                          false/* center h */, true /* center v */ );
-                suby += inc;
-            }
-
+            GUIEngine::getFont()->draw(m_sections[m_curr_section].m_entries[m_curr_element].m_subentries[i].c_str(),
+                                       core::rect< s32 >( x + 32, suby + text_offset/(1+1), x+w+32, suby+h/8 + text_offset/(1+1) ),
+                                       color,
+                                       false/* center h */, true /* center v */ );
+            suby += inc;
         }
         
-        // is it time to move on?
-        if(time_before_next_step < 0)
+    }
+    
+    // is it time to move on?
+    if(time_before_next_step < 0)
+    {
+        if(after_last_elem)
         {
-            if(after_last_elem)
-            {
-                // switch to next element
-                m_curr_section++;
-                m_curr_element = -1;
+            // switch to next element
+            m_curr_section++;
+            m_curr_element = -1;
+            time_before_next_step = TIME_SECTION_FADE;
+            
+            if(m_curr_section >= (int)m_sections.size()) reset();
+        }
+        else
+        {
+            // move on
+            m_curr_element++;
+            
+            if(m_curr_element >= (int)m_sections[m_curr_section].m_entries.size())
                 time_before_next_step = TIME_SECTION_FADE;
-                
-                if(m_curr_section >= (int)m_sections.size()) reset();
-            }
             else
             {
-                // move on
-                m_curr_element++;
-                
-                if(m_curr_element >= (int)m_sections[m_curr_section].m_entries.size())
-                    time_before_next_step = TIME_SECTION_FADE;
-                else
-                {
-                    m_time_element = 1.6f + (int)m_sections[m_curr_section].m_entries[m_curr_element].m_subentries.size()*0.5f;
-                    time_before_next_step = m_time_element;
-                }
+                m_time_element = 1.6f + (int)m_sections[m_curr_section].m_entries[m_curr_element].m_subentries.size()*0.5f;
+                time_before_next_step = m_time_element;
             }
         }
-        
-        /*
-         draw (const wchar_t *text, const core::rect< s32 > &position, video::SColor color,
-         bool hcenter=false,
-         bool vcenter=false, const core::rect< s32 > *clip=0)=0
-         */
     }
     
-    void CreditsScreen::init()
+    /*
+     draw (const wchar_t *text, const core::rect< s32 > &position, video::SColor color,
+     bool hcenter=false,
+     bool vcenter=false, const core::rect< s32 > *clip=0)=0
+     */
+}
+
+void CreditsScreen::init()
+{
+    Widget* w = getWidget<Widget>("animated_area");
+    assert(w != NULL);
+    
+    reset();
+    setArea(w->x, w->y, w->w, w->h);
+}
+
+void CreditsScreen::tearDown()
+{
+}
+
+void CreditsScreen::eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID)
+{
+    if(name == "back")
     {
-        Widget* w = getWidget<Widget>("animated_area");
-        assert(w != NULL);
-        
-        reset();
-        setArea(w->x, w->y, w->w, w->h);
+        StateManager::get()->escapePressed();
     }
-    
-    void CreditsScreen::tearDown()
-    {
-    }
-    
-    void CreditsScreen::eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID)
-    {
-        if(name == "back")
-        {
-            StateManager::get()->escapePressed();
-        }
-    }
-    
-} // end namespace
+}
+

src/states_screens/credits.hpp

@@ -23,41 +23,44 @@
 #include "guiengine/screen.hpp"
 #include "utils/ptr_vector.hpp"
 
-namespace GUIEngine
-{
-    class CreditsSection;
-    
-    class CreditsScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<CreditsScreen>
-    {
-        float m_time_element;
-        
-        ptr_vector<CreditsSection, HOLD> m_sections;
-        CreditsSection* getCurrentSection();
-        
-        int x, y, w, h;
-        core::rect< s32 > m_section_rect;
-        
-        int m_curr_section;
-        int m_curr_element;
-        
-        float time_before_next_step;
-        
-        friend class GUIEngine::ScreenSingleton<CreditsScreen>;
-        CreditsScreen();
-        
-    public:
 
-        
-        void setArea(const int x, const int y, const int w, const int h);
-        
-        // start from beginning again
-        void reset();
-        
-        void onUpdate(float dt, irr::video::IVideoDriver*);
-        
-        void init();
-        void tearDown();
-        void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
-    };
-}
+class CreditsSection;
+
+/**
+ * \brief Screen where STK credits are shown
+ * \ingroup states_screens
+ */
+class CreditsScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<CreditsScreen>
+{
+    float m_time_element;
+    
+    ptr_vector<CreditsSection, HOLD> m_sections;
+    CreditsSection* getCurrentSection();
+    
+    int x, y, w, h;
+    core::rect< s32 > m_section_rect;
+    
+    int m_curr_section;
+    int m_curr_element;
+    
+    float time_before_next_step;
+    
+    friend class GUIEngine::ScreenSingleton<CreditsScreen>;
+    CreditsScreen();
+    
+public:
+    
+    
+    void setArea(const int x, const int y, const int w, const int h);
+    
+    // start from beginning again
+    void reset();
+    
+    void onUpdate(float dt, irr::video::IVideoDriver*);
+    
+    void init();
+    void tearDown();
+    void eventCallback(GUIEngine::Widget* widget, const std::string& name, const int playerID);
+};
+
 #endif

src/states_screens/feature_unlocked.hpp

@@ -8,6 +8,10 @@ namespace irr { namespace scene { class ISceneNode; class ICameraSceneNode; clas
 class KartProperties;
 class Challenge;
 
+/**
+  * \brief Screen shown when a feature has been unlocked
+  * \ingroup states_screens
+ */
 class FeatureUnlockedCutScene : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<FeatureUnlockedCutScene>
 {
     friend class GUIEngine::ScreenSingleton<FeatureUnlockedCutScene>;

src/states_screens/grand_prix_over.hpp

@@ -6,7 +6,10 @@
 namespace irr { namespace scene { class ISceneNode; class ICameraSceneNode; class ILightSceneNode; } }
 class KartProperties;
 
-
+/**
+  * \brief Screen shown at the end of a Grand Prix
+  * \ingroup states_screens
+  */
 class GrandPrixOver : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<GrandPrixOver>
 {
     friend class GUIEngine::ScreenSingleton<GrandPrixOver>;

src/states_screens/help_screen_1.hpp

@@ -22,6 +22,10 @@
 
 namespace GUIEngine { class Widget; }
 
+/**
+  * \brief Help screen, part 1
+  * \ingroup states_screens
+  */
 class HelpScreen1 : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<HelpScreen1>
 {
     friend class GUIEngine::ScreenSingleton<HelpScreen1>;

src/states_screens/help_screen_2.hpp

@@ -22,6 +22,10 @@
 
 namespace GUIEngine { class Widget; }
 
+/**
+  * \brief Help Screen, part 2
+  * \ingroup states_screens
+  */
 class HelpScreen2 : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<HelpScreen2>
 {
     friend class GUIEngine::ScreenSingleton<HelpScreen2>;

src/states_screens/help_screen_3.hpp

@@ -22,6 +22,10 @@
 
 namespace GUIEngine { class Widget; }
 
+/**
+  * \brief Help screen, part 3
+  * \ingroup states_screens
+  */
 class HelpScreen3 : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<HelpScreen3>
 {
     friend class GUIEngine::ScreenSingleton<HelpScreen3>;

src/states_screens/kart_selection.hpp

@@ -29,6 +29,10 @@ class InputDevice;
 class PlayerKartWidget;
 class KartHoverListener;
 
+/**
+  * \brief screen where players can choose their kart
+  * \ingroup states_screens
+  */
 class KartSelectionScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<KartSelectionScreen>
 {
     friend class KartHoverListener;

src/states_screens/main_menu_screen.hpp

@@ -23,8 +23,9 @@
 namespace GUIEngine { class Widget; }
 
 /**
- * Callback handling events from the main menu
- */
+  * \brief Handles the main menu
+  * \ingroup states_screens
+  */
 class MainMenuScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<MainMenuScreen>
 {
     friend class GUIEngine::ScreenSingleton<MainMenuScreen>;

src/states_screens/options_screen_av.hpp

@@ -28,6 +28,10 @@ namespace GUIEngine { class Widget; }
 
 struct Input;
 
+/**
+  * \brief Audio/video options screen
+  * \ingroup states_screens
+  */
 class OptionsScreenAV : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<OptionsScreenAV>
 {
     OptionsScreenAV();

src/states_screens/options_screen_input.hpp

@@ -29,6 +29,10 @@ class DeviceConfig;
 
 struct Input;
 
+/**
+  * \brief Input options screen
+  * \ingroup states_screens
+  */
 class OptionsScreenInput : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<OptionsScreenInput>
 {
     OptionsScreenInput();

src/states_screens/options_screen_players.hpp

@@ -29,6 +29,10 @@ namespace GUIEngine { class Widget; }
 struct Input;
 class PlayerProfile;
 
+/**
+  * \brief Player management options screen
+  * \ingroup states_screens
+  */
 class OptionsScreenPlayers : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<OptionsScreenPlayers>
 {
 

src/states_screens/race_gui.hpp

@@ -35,6 +35,10 @@ class Kart;
 class Material;
 class RaceSetup;
 
+/**
+  * \brief Handles the in-race GUI (messages, mini-map, rankings, timer, etc...)
+  * \ingroup states_screens
+  */
 class RaceGUI
 {
 public:

src/states_screens/race_setup_screen.hpp

@@ -24,6 +24,10 @@ namespace GUIEngine { class Widget; }
 
 class GameModeRibbonListener;
 
+/**
+  * \brief Screen with race setup options (difficulty, game mode, etc...)
+  * \ingroup states_screens
+  */
 class RaceSetupScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<RaceSetupScreen>
 {
     friend class GUIEngine::ScreenSingleton<RaceSetupScreen>;

src/states_screens/state_manager.hpp

@@ -19,6 +19,8 @@
 #ifndef STATE_MANAGER_HPP
 #define STATE_MANAGER_HPP
 
+/** \defgroup states_screens */
+
 #include <string>
 #include "guiengine/abstract_state_manager.hpp"
 #include "utils/ptr_vector.hpp"
@@ -33,8 +35,17 @@ namespace GUIEngine
     class Widget;
 }
 
+/**
+  * \brief the player ID of the "game master" player
+  * the game master is the player that can perform the game setup
+  * \ingroup states_screens
+  */
 const static int PLAYER_ID_GAME_MASTER = 0;
 
+/**
+  * \brief A concrete scene manager, derived from GUIEngine's AbastractSceneManager
+  * \ingroup states_screens
+  */
 class StateManager : public GUIEngine::AbstractStateManager
 {
     

src/states_screens/tracks_screen.hpp

@@ -23,6 +23,10 @@
 
 namespace GUIEngine { class Widget; }
 
+/**
+  * \brief screen where the user can select a track
+  * \ingroup states_screens
+  */
 class TracksScreen : public GUIEngine::Screen, public GUIEngine::ScreenSingleton<TracksScreen>
 {
     friend class GUIEngine::ScreenSingleton<TracksScreen>;