Some coding style changes (mostly comments)

Sorry for the big recompile because of it, had some of these
after some experimenting and it was clouding my svn diff.


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

src/animations/three_d_animation.cpp

@@ -271,12 +271,12 @@ ThreeDAnimation::~ThreeDAnimation()
         World::getWorld()->getPhysics()->removeBody(m_body);
         delete m_body;
         delete m_motion_state;
-		// If an exact shape was used, the collision shape pointer
+        // If an exact shape was used, the collision shape pointer
-		// here is a copy of the collision shape pointer in the
+        // here is a copy of the collision shape pointer in the
-		// triangle mesh. In order to avoid double-freeing this
+        // triangle mesh. In order to avoid double-freeing this
-		// pointer, we don't free the pointer in this case.
+        // pointer, we don't free the pointer in this case.
         if(!m_triangle_mesh)
-			delete m_collision_shape;
+            delete m_collision_shape;
     }
     
     if (m_triangle_mesh)

src/guiengine/screen.cpp

@@ -39,7 +39,14 @@ using namespace GUIEngine;
 #include <assert.h>
 
 // -----------------------------------------------------------------------------
-
+/** 
+ * \brief          Creates a screen populated by the widgets described
+ *                 in a STK GUI file.
+ * \param filename Name of the XML file describing the screen.
+ *                 This is NOT a path.
+ *                 The passed file name will be searched for in the
+ *                 STK data/gui directory.
+ */
 Screen::Screen(const char* file, bool pause_race)
 {
     m_magic_number   = 0xCAFEC001;
@@ -52,7 +59,9 @@ Screen::Screen(const char* file, bool pause_race)
 }   // Screen
 
 // -----------------------------------------------------------------------------
-
+/** \brief Creates a dummy incomplete object; only use to override behaviour
+ *         in sub-class.
+ */
 Screen::Screen(bool pause_race)
 {
     m_magic_number = 0xCAFEC001;
@@ -88,7 +97,8 @@ void Screen::init()
 /** Prepares removal of this screen. If necessary this will unpause the
  *  race (so this means that if you have several consecutive screens while
  *  the race is running the race will be unpaused and paused when switching
- *  from one screen to the next. */
+ *  from one screen to the next.
+ */
 void Screen::tearDown()
 {
     if(m_pause_race && World::getWorld())
@@ -102,7 +112,7 @@ void Screen::tearDown()
 #pragma mark Load/Init
 #endif
 
-
+/** \brief loads this Screen from the file passed to the constructor */
 void Screen::loadFromFile()
 {
     assert(m_magic_number == 0xCAFEC001);
@@ -126,7 +136,10 @@ void Screen::loadFromFile()
 }   // loadFromFile
 
 // -----------------------------------------------------------------------------
-
+/** Next time this menu needs to be shown, don't use cached values,
+ *  re-calculate everything. (useful e.g. on reschange, when sizes have changed
+ *  and must be re-calculated)
+ */
 void Screen::unload()
 {
     assert(m_magic_number == 0xCAFEC001);
@@ -144,7 +157,9 @@ void Screen::unload()
 }   // unload
 
 // -----------------------------------------------------------------------------
-
+/** \brief Called after all widgets have been added. namely expands layouts
+ *         into absolute positions.
+ */
 void Screen::calculateLayout()
 {
     assert(m_magic_number == 0xCAFEC001);
@@ -158,7 +173,9 @@ void Screen::calculateLayout()
 #pragma mark Adding/Removing widgets
 #endif
 
-
+/** \brief Adds the IrrLicht widgets corresponding to this screen to the
+ *         IGUIEnvironment.
+ */
 void Screen::addWidgets()
 {
     assert(m_magic_number == 0xCAFEC001);
@@ -176,7 +193,9 @@ void Screen::addWidgets()
 }   // addWidgets
 
 // -----------------------------------------------------------------------------
-
+/** \brief Can be used for custom purposes for which the load-screen-from-XML
+ *         code won't make it.
+ */
 void Screen::manualAddWidget(Widget* w)
 {
     assert(m_magic_number == 0xCAFEC001);
@@ -184,7 +203,8 @@ void Screen::manualAddWidget(Widget* w)
 }   // manualAddWidget
 
 // -----------------------------------------------------------------------------
-
+/** \brief Can be used for custom purposes for which the load-screen-from-XML
+ *         code won't make it. */
 void Screen::manualRemoveWidget(Widget* w)
 {
     assert(m_magic_number == 0xCAFEC001);
@@ -207,7 +227,7 @@ void Screen::manualRemoveWidget(Widget* w)
 #endif
 
 // -----------------------------------------------------------------------------
-
+/** \brief Implementing method from AbstractTopLevelContainer */
 int Screen::getWidth()
 {
     core::dimension2d<u32> frame_size = GUIEngine::getDriver()->getCurrentRenderTargetSize();
@@ -215,7 +235,7 @@ int Screen::getWidth()
 }
 
 // -----------------------------------------------------------------------------
-
+/** \brief Implementing method from AbstractTopLevelContainer */
 int Screen::getHeight()
 {
     core::dimension2d<u32> frame_size = GUIEngine::getDriver()->getCurrentRenderTargetSize();

src/guiengine/screen.hpp

@@ -88,7 +88,8 @@ namespace GUIEngine
      * Mainly responsible of its children widgets; Screen lays them
      * out, asks them to add themselves, asks them to remove themselves, etc.
      *
-     * Also initiates the read of GUI files, even though most of that work is done in "screen_loader.cpp"
+     * Also initiates the read of GUI files, even though most of that work is
+     * done in "screen_loader.cpp"
      *
      * \ingroup guiengine
      */
@@ -100,13 +101,15 @@ namespace GUIEngine
          *  running while it is being shown. */
         bool m_pause_race;
 
-    private:
         friend class Skin;
 
         bool m_loaded;
+
         std::string m_filename;
 
-        /** Will be called to determine if the 3D scene must be rendered when at this screen. */
+        /** Will be called to determine if the 3D scene must be rendered when
+         *  at this screen.
+         */
         bool m_render_3d;
 
         /** to catch errors as early as possible, for debugging purposes only */
@@ -122,28 +125,24 @@ namespace GUIEngine
         /**
          * \ingroup guiengine
          * \brief Loads a GUI screen from its XML file.
-         * Builds a hierarchy of Widget objects whose contents are a direct transcription of the XML file,
+         *
-         * with little analysis or layout performed on them.
+         * Builds a hierarchy of Widget objects whose contents are a direct
+         * transcription of the XML file, with little analysis or layout
+         * performed on them.
          */
-        static void parseScreenFileDiv(irr::io::IXMLReader* xml, PtrVector<Widget>& append_to,
+        static void parseScreenFileDiv(irr::io::IXMLReader* xml,
+                                       PtrVector<Widget>& append_to,
                                        irr::gui::IGUIElement* parent = NULL);
 
 
-        /** \brief creates a dummy incomplete object; only use to override behaviour in sub-class */
         Screen(bool pause_race=true);
 
-        /** 
-          * \brief          creates a screen populated by the widgets described in a STK GUI file
-          * \param filename name of the XML file describing the screen. this is NOT a path.
-          *                 The passed file name will be searched for in the STK data/gui directory
-          */
         Screen(const char* filename, bool pause_race=true);
 
         virtual ~Screen();
 
         bool operator ==(const char* filename) const { return m_filename == filename; }
 
-        /** \brief loads this Screen from the file passed to the constructor */
         void loadFromFile();
 
         /** \return whether this screen is currently loaded */
@@ -151,134 +150,146 @@ namespace GUIEngine
 
         bool throttleFPS() const { return m_throttle_FPS; }
 
-        /** \brief adds the irrLicht widgets corresponding to this screen to the IGUIEnvironment */
         void addWidgets();
 
-        /** \brief called after all widgets have been added. namely expands layouts into absolute positions */
         void calculateLayout();
 
-        /** \brief can be used for custom purposes for which the load-screen-from-XML code won't make it */
         void manualAddWidget(Widget* w);
 
-        /** \brief can be used for custom purposes for which the load-screen-from-XML code won't make it */
         void manualRemoveWidget(Widget* w);
 
         /** \return the name of this menu (which is the name of the file) */
         const std::string& getName() const { return m_filename; }
 
-        /** Next time this menu needs to be shown, don't use cached values, re-calculate everything.
-         (useful e.g. on reschange, when sizes have changed and must be re-calculated) */
         virtual void unload();
 
-        /** Will be called to determine if the 3D scene must be rendered when at this screen */
+        /** Will be called to determine if the 3D scene must be rendered when
+         *  at this screen
+         */
         bool needs3D() { return m_render_3d; }
 
-        /** \brief invoke this method for screens that use a 3D scene as background
+        /** \brief Invoke this method for screens that use a 3D scene as
-          *
+         *         background.
-          * (if this method is not invoked with 'true' as parameter, the menu background will
+         *
-          *  be rendered instead).
+         *  (if this method is not invoked with 'true' as parameter, the menu
-          *
+         *  background will be rendered instead).
-          * \note to create the 3D background, use the facilities provided by the irrLicht scene
+         *
-          *       manager, this class will not set up any 3D scene.
+         *  \note To create the 3D background, use the facilities provided by
-          */
+         *        the irrLicht scene manager, this class will not set up any
+         *        3D scene.
+         */
         void setNeeds3D(bool needs3D) { m_render_3d = needs3D; }
 
         /** 
-          * \brief callback invoked when loading this menu
+         * \brief Callback invoked when loading this menu.
-          *
+         *
-          * \pre Children widgets of this menu have been created by the time this callback
+         * \pre   Children widgets of this menu have been created by the time
-          *               is invoked.
+         *        this callback is invoked.
-          * \note this method is not called everytime the screen is shown. Screen::init is.
+         * \note  This method is not called everytime the screen is shown.
-          *       use this method for persistent setup code (namely, that deals with settupping
+         *        Screen::init is.
-          *       children widget objects and needs not be done everytime we visit the screen).
+         *        Use this method for persistent setup code (namely, that
-          * \note a Screen object instance may be unloaded then loaded back. This method might thus
+         *        deals with setting up children widget objects and needs not
-          *       be called more than once in the lifetime of a Screen object, however there will always
+         *        be done everytime we visit the screen).
-          *       be an 'unload' event in-between calls to this method.
+         * \note  A Screen object instance may be unloaded then loaded back.
-          */
+         *        This method might thus be called more than once in the
+         *        lifetime of a Screen object, however there will always
+         *        be an 'unload' event in-between calls to this method.
+         */
         virtual void loadedFromFile() = 0;
 
         /**
-          * \brief callback invoked when this screen is being unloaded
+          * \brief Callback invoked when this screen is being unloaded.
-          * Override this method in children classes if you need to be notified of this.
+          *        Override this method in children classes if you need to be
-          * \note a Screen object instance may be unloaded then loaded back at will.
+          *        notified of this.
-          * \note an unloaded Screen object does not have its children widgets anymore, it only
+          * \note  A Screen object instance may be unloaded then loaded back
-          *       retains its members (most importantly the path to its GUI file) so that it can be
+          *        at will.
-          *       loaded back later.
+          * \note  An unloaded Screen object does not have its children widgets
+          *        anymore, it only retains its members (most importantly the
+          *        path to its GUI file) so that it can be loaded back later.
           */
         virtual void unloaded() {}
 
         /**
-          * \brief Optional callback invoked very early, before widgets have been added (contrast with
+          * \brief Optional callback invoked very early, before widgets have
-          *        init(), which is invoked afer widgets were added)
+          *        been added (contrast with init(), which is invoked afer
+          *        widgets were added)
           */
         virtual void beforeAddingWidget() {}
 
         /** 
-          * \brief callback invoked when entering this menu (after the widgets have been added)
+          * \brief Callback invoked when entering this menu (after the
+          *        widgets have been added).
           *
-          * \note the same instance of your object may be entered/left more than once, so make sure that
+          * \note  The same instance of your object may be entered/left more
-          * one instance of your object can be used several times if the same screen is visited several
+          *        than once, so make sure that one instance of your object
-          * times.
+          *        can be used several times if the same screen is visited
+          *        several times.
           */
         virtual void init();
 
         /** 
-          * \brief callback invoked before leaving this menu
+          * \brief Callback invoked before leaving this menu.
           *
-          * @note the same instance of your object may be entered/left more than once, so make sure that
+          * \note  The same instance of your object may be entered/left more
-          * one instance of your object can be used several times if the same screen is visited several
+          *        than once, so make sure that one instance of your object can
-          * times.
+          *        be used several times if the same screen is visited several
+          *        times.
           */
         virtual void tearDown();
 
         /** 
           * \brief  Called when escape is pressed.
-          * \return true if the screen should be closed, false if you handled the press another way
+          * \return true if the screen should be closed,
+          *         false if you handled the press another way
           */
         virtual bool onEscapePressed() { return true; }
 
         /**
          * \brief will be called everytime something happens.
-         * Events are generally a widget state change. In this case, a pointer to the said widget is
+         *
-         * passed along its name, so you get its new state and/or act. There are two special events, passed
+         * Events are generally a widget state change. In this case, a pointer
-         * with a NULL widget, and which bear the anmes "init" and "tearDown", called respectively when a
+         * to the said widget is passed along its name, so you get its new
-         * screen is being made visible and when it's being left, allowing for setup/clean-up.
+         * state and/or act. There are two special events, passed with a NULL
+         * widget, and which bear the names "init" and "tearDown", called
+         * respectively when a screen is being made visible and when it's being
+         * left, allowing for setup/clean-up.
          */
         virtual void eventCallback(Widget* widget, const std::string& name, const int playerID) = 0;
 
         /**
-          * \brief optional callback you can override to be notified at every frame.
+         * \brief optional callback you can override to be notified at every frame.
-          */
+         */
         virtual void onUpdate(float dt, irr::video::IVideoDriver*) { };
 
         /**
-          * \return which music to play at this screen
+         * \return which music to play at this screen
-          */
+         */
         virtual MusicInformation* getMusic() const { return stk_config->m_title_music; }
 
-        /**
-          * \brief Implementing method from AbstractTopLevelContainer
-          */
         virtual int getWidth();
 
-        /**
-          * \brief Implementing method from AbstractTopLevelContainer
-          */
         virtual int getHeight();
 
         /**
-          * \brief override this if you need to be notified of player actions in subclasses
+         * \brief Override this if you need to be notified of player actions
-          */
+         *        in subclasses.
-        virtual EventPropagation filterActions(PlayerAction action, int deviceID, const unsigned int value,
+         */
-                                               Input::InputType type, int playerId) { return EVENT_LET; }
+        virtual EventPropagation filterActions(PlayerAction action,
+                                               int deviceID,
+                                               const unsigned int value,
+                                               Input::InputType type,
+                                               int playerId) 
+            { return EVENT_LET; }
 
-        /** Callback you can use if you want to know when the user pressed on a disabled ribbon item
+        /** Callback you can use if you want to know when the user pressed
-         * (the main I see for this is to give feedback)
+         *  on a disabled ribbon item.
+         *  (the main use I see for this is to give feedback)
          */
         virtual void onDisabledItemClicked(const std::string& item) {}
 
         /**
-         * \brief override this if you need to be notified of raw input in subclasses
+         * \brief Override this if you need to be notified of raw input in
+         *        subclasses.
          */
         virtual void filterInput(Input::InputType type,
                                  int deviceID,

src/guiengine/screen_loader.cpp

@@ -255,7 +255,8 @@ if(prop_name != NULL) widget.m_properties[prop_flag] = core::stringc(prop_name).
                 if (wcscmp(L"topbar", xml->getNodeName()) == 0)
                     return;
                 
-                // we're done parsing this 'ribbon', return one step back in the recursive call
+                // We're done parsing this 'ribbon', return one step back in
+                // the recursive call.
                 if (wcscmp(L"ribbon", xml->getNodeName()) == 0 ||
                     wcscmp(L"buttonbar", xml->getNodeName()) == 0 ||
                     wcscmp(L"tabs", xml->getNodeName()) == 0)

src/states_screens/help_screen_1.cpp

@@ -28,19 +28,19 @@ using namespace GUIEngine;
 
 DEFINE_SCREEN_SINGLETON( HelpScreen1 );
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 HelpScreen1::HelpScreen1() : Screen("help1.stkgui")
 {
 }   // HelpScreen1
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen1::loadedFromFile()
 {
 }   // loadedFromFile
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen1::eventCallback(Widget* widget, const std::string& name, const int playerID)
 {
@@ -52,7 +52,7 @@ void HelpScreen1::eventCallback(Widget* widget, const std::string& name, const i
         //else
         if (selection == "page2") StateManager::get()->replaceTopMostScreen(HelpScreen2::getInstance());
         else if (selection == "page3") StateManager::get()->replaceTopMostScreen(HelpScreen3::getInstance());
-        else if(selection == "page4") StateManager::get()->replaceTopMostScreen(HelpScreen4::getInstance());
+        else if (selection == "page4") StateManager::get()->replaceTopMostScreen(HelpScreen4::getInstance());
     }
     else if (name == "back")
     {
@@ -60,7 +60,7 @@ void HelpScreen1::eventCallback(Widget* widget, const std::string& name, const i
     }
 }   // eventCallback
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen1::init()
 {
@@ -70,4 +70,4 @@ void HelpScreen1::init()
     if (w != NULL)  w->select( "page1", PLAYER_ID_GAME_MASTER );
 }   //init
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------

src/states_screens/help_screen_2.cpp

@@ -28,19 +28,19 @@ using namespace GUIEngine;
 
 DEFINE_SCREEN_SINGLETON( HelpScreen2 );
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 HelpScreen2::HelpScreen2() : Screen("help2.stkgui")
 {
 }   // HelpScreen2
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen2::loadedFromFile()
 {
 }   // loadedFromFile
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen2::eventCallback(Widget* widget, const std::string& name, const int playerID)
 {
@@ -59,7 +59,7 @@ void HelpScreen2::eventCallback(Widget* widget, const std::string& name, const i
     }
 }   // eventCallback
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen2::init()
 {
@@ -69,4 +69,4 @@ void HelpScreen2::init()
     if (w != NULL) w->select( "page2", PLAYER_ID_GAME_MASTER );
 }   // init
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------

src/states_screens/help_screen_3.cpp

@@ -29,19 +29,19 @@ using namespace GUIEngine;
 
 DEFINE_SCREEN_SINGLETON( HelpScreen3 );
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 HelpScreen3::HelpScreen3() : Screen("help3.stkgui")
 {
 }   // HelpSCreen3
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen3::loadedFromFile()
 {
 }   // loadedFromFile
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen3::eventCallback(Widget* widget, const std::string& name, const int playerID)
 {
@@ -60,7 +60,7 @@ void HelpScreen3::eventCallback(Widget* widget, const std::string& name, const i
     }
 }   // eventCallback
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen3::init()
 {
@@ -70,4 +70,4 @@ void HelpScreen3::init()
     if (w != NULL) w->select( "page3", PLAYER_ID_GAME_MASTER );
 }   // init
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------

src/states_screens/help_screen_4.cpp

@@ -29,19 +29,19 @@ using namespace GUIEngine;
 
 DEFINE_SCREEN_SINGLETON( HelpScreen4 );
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 HelpScreen4::HelpScreen4() : Screen("help4.stkgui")
 {
 }   // HelpScreen4
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen4::loadedFromFile()
 {
 }   // loadedFromFile
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen4::eventCallback(Widget* widget, const std::string& name, const int playerID)
 {
@@ -59,7 +59,7 @@ void HelpScreen4::eventCallback(Widget* widget, const std::string& name, const i
     }
 }   // eventCallback
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
 
 void HelpScreen4::init()
 {
@@ -69,4 +69,4 @@ void HelpScreen4::init()
     if (w != NULL) w->select( "page4", PLAYER_ID_GAME_MASTER );
 }   // init
 
-// ------------------------------------------------------------------------------------------------------
+// -----------------------------------------------------------------------------