Some trivial documentation work. Fixes all Doxygen warnings.

12 files changed, 80 insertions, 48 deletions

diff --git a/src/being.cpp b/src/being.cpp
index ac003d1c..68b85832 100644
--- a/src/being.cpp
+++ b/src/being.cpp
@@ -42,8 +42,8 @@
 
 extern Spriteset *emotionset;
 
-PATH_NODE::PATH_NODE(Uint16 iX, Uint16 iY):
-    x(iX), y(iY)
+PATH_NODE::PATH_NODE(unsigned short x, unsigned short y):
+    x(x), y(y)
 {
 }
 
@@ -486,7 +486,7 @@ Being::draw(Graphics *graphics, int offsetX, int offsetY) const
 }
 
 void
-Being::drawEmotion(Graphics *graphics, Sint32 offsetX, Sint32 offsetY)
+Being::drawEmotion(Graphics *graphics, int offsetX, int offsetY)
 {
     if (!mEmotion)
         return;
@@ -498,7 +498,7 @@ Being::drawEmotion(Graphics *graphics, Sint32 offsetX, Sint32 offsetY)
 }
 
 void
-Being::drawSpeech(Graphics *graphics, Sint32 offsetX, Sint32 offsetY)
+Being::drawSpeech(Graphics *graphics, int offsetX, int offsetY)
 {
     int px = mPx + offsetX;
     int py = mPy + offsetY;
diff --git a/src/being.h b/src/being.h
index bfd01568..b87cacbe 100644
--- a/src/being.h
+++ b/src/being.h
@@ -146,7 +146,7 @@ class Being : public Sprite
          * Puts a damage bubble above this being for the specified amount
          * of time.
          *
-         * @param text The text that should appear.
+         * @param amount The amount of damage.
          * @param time The amount of time the text should stay in milliseconds.
          */
         void setDamage(Sint16 amount, Uint32 time);
@@ -160,7 +160,7 @@ class Being : public Sprite
         /**
          * Sets the name for the being.
          *
-         * @param text The name that should appear.
+         * @param name The name that should appear.
          */
         void
         setName(const std::string &name) { mName = name; }
@@ -223,19 +223,19 @@ class Being : public Sprite
          * Draws the speech text above the being.
          */
         void
-        drawSpeech(Graphics *graphics, Sint32 offsetX, Sint32 offsetY);
+        drawSpeech(Graphics *graphics, int offsetX, int offsetY);
 
         /**
          * Draws the emotion picture above the being.
          */
         void
-        drawEmotion(Graphics *graphics, Sint32 offsetX, Sint32 offsetY);
+        drawEmotion(Graphics *graphics, int offsetX, int offsetY);
 
         /**
          * Draws the name text below the being.
          */
         virtual void
-        drawName(Graphics *graphics, Sint32 offsetX, Sint32 offsetY) {};
+        drawName(Graphics *graphics, int offsetX, int offsetY) {};
 
         /**
          * Returns the type of the being.
@@ -315,7 +315,7 @@ class Being : public Sprite
          * @see Sprite::draw(Graphics, int, int)
          */
         virtual void
-        draw(Graphics *graphics, Sint32 offsetX, Sint32 offsetY) const;
+        draw(Graphics *graphics, int offsetX, int offsetY) const;
 
         /**
          * Returns the pixel X coordinate.
diff --git a/src/beingmanager.h b/src/beingmanager.h
index 15a347de..f97a23f4 100644
--- a/src/beingmanager.h
+++ b/src/beingmanager.h
@@ -68,8 +68,11 @@ class BeingManager
         /**
          * Return a being nearest to specific coordinates.
          *
-         * \param maxdist maximal distance. If minimal distance is larger,
-         *                no being is returned
+         * @param x       X coordinate.
+         * @param y       Y coordinate.
+         * @param maxdist Maximal distance. If minimal distance is larger,
+         *                no being is returned.
+         * @param type    The type of being to look for.
          */
         Being* findNearestLivingBeing(Uint16 x, Uint16 y, int maxdist,
                                       Being::Type type = Being::UNKNOWN);
diff --git a/src/gui/window.h b/src/gui/window.h
index 9ac02287..31c260cf 100644
--- a/src/gui/window.h
+++ b/src/gui/window.h
@@ -50,11 +50,11 @@ class Window : public gcn::Window
          * Constructor. Initializes the title to the given text and hooks
          * itself into the window container.
          *
-         * @param text   The initial window title, "Window" by default.
-         * @param modal  Block input to other windows.
-         * @param parent The parent window. This is the window standing above
-         *               this one in the window hiearchy. When reordering,
-         *               a window will never go below its parent window.
+         * @param caption The initial window title, "Window" by default.
+         * @param modal   Block input to other windows.
+         * @param parent  The parent window. This is the window standing above
+         *                this one in the window hiearchy. When reordering,
+         *                a window will never go below its parent window.
          */
         Window(const std::string &caption = "Window", bool modal = false,
                 Window *parent = NULL);
diff --git a/src/main.h b/src/main.h
index 6ecf628e..c001a374 100644
--- a/src/main.h
+++ b/src/main.h
@@ -38,7 +38,7 @@
  * During the game, the current Map is displayed by the main Viewport, which
  * is the bottom-most widget in the WindowContainer. Aside the viewport, the
  * window container keeps track of all the \link Window Windows\endlink
- * displayed during the game.
+ * displayed during the game. It is the <i>top</i> widget for Guichan.
  *
  * A Map is composed of several layers of \link Image Images\endlink (tiles),
  * a layer with collision information and \link Sprite Sprites\endlink. The
diff --git a/src/properties.h b/src/properties.h
index 56e90c0e..bcd114c1 100644
--- a/src/properties.h
+++ b/src/properties.h
@@ -34,13 +34,17 @@
 class Properties
 {
     public:
+        /**
+         * Destructor.
+         */
         virtual
         ~Properties() {}
 
         /**
          * Get a map property.
          *
-         * @param def default value, empty string by default
+         * @param name The name of the property.
+         * @param def  Default value, empty string by default.
          * @return the value of the given property or the given default when it
          *         doesn't exist.
          */
@@ -54,7 +58,8 @@ class Properties
         /**
          * Gets a map property as a float.
          *
-         * @param def default value, 0.0f by default
+         * @param name The name of the property.
+         * @param def  Default value, 0.0f by default.
          * @return the value of the given property, or 0.0f when it doesn't
          *         exist.
          */
@@ -74,6 +79,10 @@ class Properties
 
         /**
          * Returns whether a certain property is available.
+         *
+         * @param name The name of the property.
+         * @return <code>true</code> when a property is defined,
+         *         <code>false</code> otherwise.
          */
         bool
         hasProperty(const std::string &name)
@@ -83,6 +92,9 @@ class Properties
 
         /**
          * Set a map property.
+         *
+         * @param name  The name of the property.
+         * @param value The value of the property.
          */
         void
         setProperty(const std::string &name, const std::string &value)
diff --git a/src/resources/image.h b/src/resources/image.h
index a1ab7f48..03bf0cbc 100644
--- a/src/resources/image.h
+++ b/src/resources/image.h
@@ -62,6 +62,7 @@ class Image : public Resource
          *
          * @param buffer     The memory buffer containing the image data.
          * @param bufferSize The size of the memory buffer in bytes.
+         * @param idPath     The path identifying the resource.
          *
          * @return <code>NULL</code> if the an error occurred, a valid pointer
          *         otherwise.
diff --git a/src/resources/mapreader.h b/src/resources/mapreader.h
index ad21762d..d16ff1d5 100644
--- a/src/resources/mapreader.h
+++ b/src/resources/mapreader.h
@@ -55,8 +55,9 @@ class MapReader
         /**
          * Reads the properties element.
          *
-         * @param props the Properties instance to which the properties will
-         *              be assigned
+         * @param node  The <code>properties</code> element.
+         * @param props The Properties instance to which the properties will
+         *              be assigned.
          */
         static void
         readProperties(xmlNodePtr node, Properties* props);
diff --git a/src/resources/music.h b/src/resources/music.h
index 9cf75928..2888eaa0 100644
--- a/src/resources/music.h
+++ b/src/resources/music.h
@@ -44,6 +44,7 @@ class Music : public Resource
          *
          * @param buffer     The memory buffer containing the music data.
          * @param bufferSize The size of the memory buffer in bytes.
+         * @param idPath     The path identifying the resource.
          *
          * @return <code>NULL</code> if the an error occurred, a valid pointer
          *         otherwise.
diff --git a/src/resources/soundeffect.h b/src/resources/soundeffect.h
index 92b0016a..007f5a77 100644
--- a/src/resources/soundeffect.h
+++ b/src/resources/soundeffect.h
@@ -45,6 +45,7 @@ class SoundEffect : public Resource
          *
          * @param buffer     The memory buffer containing the sample data.
          * @param bufferSize The size of the memory buffer in bytes.
+         * @param idPath     The path identifying the resource.
          *
          * @return <code>NULL</code> if the an error occurred, a valid pointer
          *         otherwise.
diff --git a/src/sound.cpp b/src/sound.cpp
index 8ba8fe99..9f858e15 100644
--- a/src/sound.cpp
+++ b/src/sound.cpp
@@ -40,7 +40,8 @@ Sound::~Sound()
 {
 }
 
-void Sound::init()
+void
+Sound::init()
 {
     // Don't initialize sound engine twice
     if (mInstalled) return;
@@ -71,7 +72,8 @@ void Sound::init()
     mInstalled = true;
 }
 
-void Sound::info()
+void
+Sound::info()
 {
     SDL_version compiledVersion;
     const SDL_version *linkedVersion;
@@ -110,7 +112,8 @@ void Sound::info()
     logger->log("Sound::info() Channels: %i", channels);
 }
 
-void Sound::setMusicVolume(int volume)
+void
+Sound::setMusicVolume(int volume)
 {
     if (!mInstalled) return;
 
@@ -118,7 +121,8 @@ void Sound::setMusicVolume(int volume)
     Mix_VolumeMusic(volume);
 }
 
-void Sound::setSfxVolume(int volume)
+void
+Sound::setSfxVolume(int volume)
 {
     if (!mInstalled) return;
 
@@ -126,7 +130,8 @@ void Sound::setSfxVolume(int volume)
     Mix_Volume(-1, volume);
 }
 
-void Sound::playMusic(const char *path, int loop)
+void
+Sound::playMusic(const std::string &path, int loop)
 {
     if (!mInstalled) return;
 
@@ -134,9 +139,10 @@ void Sound::playMusic(const char *path, int loop)
         stopMusic();
     }
 
-    logger->log("Sound::startMusic() Playing \"%s\" %i times", path, loop);
+    logger->log("Sound::startMusic() Playing \"%s\" %i times", path.c_str(),
+                loop);
 
-    mMusic = Mix_LoadMUS(path);
+    mMusic = Mix_LoadMUS(path.c_str());
     if (mMusic) {
         Mix_PlayMusic(mMusic, loop);
     }
@@ -145,7 +151,8 @@ void Sound::playMusic(const char *path, int loop)
     }
 }
 
-void Sound::stopMusic()
+void
+Sound::stopMusic()
 {
     if (!mInstalled) return;
 
@@ -158,7 +165,8 @@ void Sound::stopMusic()
     }
 }
 
-void Sound::fadeInMusic(const char *path, int loop, int ms)
+void
+Sound::fadeInMusic(const std::string &path, int loop, int ms)
 {
     if (!mInstalled) return;
 
@@ -166,10 +174,11 @@ void Sound::fadeInMusic(const char *path, int loop, int ms)
         stopMusic();
     }
 
-    logger->log("Sound::fadeInMusic() Fading \"%s\" %i times (%i ms)", path,
-            loop, ms);
+    logger->log("Sound::fadeInMusic() Fading \"%s\" %i times (%i ms)",
+                path.c_str(),
+                loop, ms);
 
-    mMusic = Mix_LoadMUS(path);
+    mMusic = Mix_LoadMUS(path.c_str());
     if (mMusic) {
         Mix_FadeInMusic(mMusic, loop, ms);
     }
@@ -178,7 +187,8 @@ void Sound::fadeInMusic(const char *path, int loop, int ms)
     }
 }
 
-void Sound::fadeOutMusic(int ms)
+void
+Sound::fadeOutMusic(int ms)
 {
     if (!mInstalled) return;
 
@@ -191,7 +201,8 @@ void Sound::fadeOutMusic(int ms)
     }
 }
 
-void Sound::playSfx(const std::string &path)
+void
+Sound::playSfx(const std::string &path)
 {
     if (!mInstalled || path.length() == 0) return;
 
@@ -203,7 +214,8 @@ void Sound::playSfx(const std::string &path)
     }
 }
 
-void Sound::close()
+void
+Sound::close()
 {
     stopMusic();
 
diff --git a/src/sound.h b/src/sound.h
index 07db0587..ebcd6442 100644
--- a/src/sound.h
+++ b/src/sound.h
@@ -62,10 +62,10 @@ class Sound {
         /**
          * Starts background music.
          *
-         * \param in   Full path to file
-         * \param loop The number of times the song is played (-1 = infinite)
+         * @param path The full path to the music file.
+         * @param loop The number of times the song is played (-1 = infinite)
          */
-        void playMusic(const char *path, int loop = -1);
+        void playMusic(const std::string &path, int loop = -1);
 
         /**
          * Stops currently running background music track.
@@ -75,37 +75,38 @@ class Sound {
         /**
          * Fades in background music.
          *
-         * \param in   Full path to file
-         * \param loop The number of times the song is played (-1 = infinite)
-         * \param ms   Duration of fade-in effect (ms)
+         * @param path The full path to the music file.
+         * @param loop The number of times the song is played (-1 = infinite)
+         * @param ms   Duration of fade-in effect (ms)
          */
-        void fadeInMusic(const char *path, int loop = -1, int ms = 2000);
+        void fadeInMusic(const std::string &path, int loop = -1,
+                         int ms = 2000);
 
         /**
          * Fades out currently running background music track.
          *
-         * \param ms   Duration of fade-out effect (ms)
+         * @param ms   Duration of fade-out effect (ms)
          */
         void fadeOutMusic(int ms);
 
         /**
          * Sets music volume.
          *
-         * \param volume Volume value
+         * @param volume Volume value
          */
         void setMusicVolume(int volume);
 
         /**
          * Sets sfx volume.
          *
-         * \param volume Volume value
+         * @param volume Volume value
          */
         void setSfxVolume(int volume);
 
         /**
          * Plays an item.
          *
-         * \param path     Full path to file
+         * @param path The resource path to the sound file.
          */
         void playSfx(const std::string &path);