Documentation: Fixed a heap of Doxygen errors

This brings the Doxygen error count down to ~800 from the 1100 that
was the situation a couple of weeks ago.

doomsday/engine/api/dd_fontrenderer.h

@@ -159,15 +159,29 @@ void FR_SetCaseScale(boolean value);
 
 /**
  * Draw a text block.
+ * @note Member of the Doomsday public API.
  *
- * @param text  Block of text to be drawn.
+ * @param text    Block of text to be drawn.
  * @param origin  Orient drawing about this offset (topleft:[0,0]).
+ */
+void FR_DrawText(const char* text, const Point2Raw* origin);
+
+/**
+ * @copydoc FR_DrawText()
  * @param alignFlags  @ref alignmentFlags
- * @param flags  @ref drawTextFlags
  */
-void FR_DrawText3(const char* text, const Point2Raw* origin, int alignFlags, short flags);
 void FR_DrawText2(const char* text, const Point2Raw* origin, int alignFlags);
-void FR_DrawText(const char* text, const Point2Raw* origin);
+
+/**
+ * Draw a text block.
+ * @note Member of the Doomsday public API.
+ *
+ * @param text        Block of text to be drawn.
+ * @param _origin     Orient drawing about this offset (topleft:[0,0]).
+ * @param alignFlags  @ref alignmentFlags
+ * @param _textFlags  @ref drawTextFlags
+ */
+void FR_DrawText3(const char* text, const Point2Raw* _origin, int alignFlags, short _textFlags);
 
 void FR_DrawTextXY3(const char* text, int x, int y, int alignFlags, short flags);
 void FR_DrawTextXY2(const char* text, int x, int y, int alignFlags);

doomsday/engine/api/dd_share.h

@@ -29,12 +29,9 @@
 extern "C" {
 #endif
 
-/**
- * @def C_DECL
- * Calling convention for compare functions. Only for Windows.
- */
 #ifndef C_DECL
 #  if defined(WIN32)
+/// Defines the calling convention for compare functions. Only used on Windows.
 #    define C_DECL __cdecl
 #  elif defined(UNIX)
 #    define C_DECL

doomsday/engine/portable/include/blockset.h

@@ -81,7 +81,7 @@ void BlockSet_Delete(blockset_t* set);
 /**
  * Return a ptr to the next unused element in the blockset.
  *
- * @param blockset  The blockset to return the next element from.
+ * @param set  The blockset to return the next element from.
  *
  * @return  Ptr to the next unused element in the blockset.
  */

doomsday/engine/portable/include/cbuffer.h

@@ -127,6 +127,7 @@ const cbline_t* CBuffer_GetLine(CBuffer* cb, uint idx);
  * Collate an array of ptrs to the immutable @c cbline_t objects owned by
  * the cbuffer. Caller retains ownership of @a list.
  *
+ * @param cb            CBuffer instance.
  * @param reqCount      Number of lines requested from the buffer, zero means
  *                      use the current number of lines as the limit.
  * @param firstIdx      Line index of the first line to be retrieved. If

doomsday/engine/portable/include/colorpalette.h

@@ -72,7 +72,7 @@ ushort ColorPalette_Size(colorpalette_t* pal);
  * @param compOrder  Component order. Examples:
  * <pre> [0,1,2] == RGB
  * [2,1,0] == BGR</pre>
- * @param compSize  Number of bits per component [R,G,B].
+ * @param compBits  Number of bits per component [R,G,B].
  * @param colorData  Color triplets (at least @a numColors * 3).
  * @param colorCount  Number of color triplets.
  */
@@ -94,10 +94,12 @@ void ColorPalette_Color(const colorpalette_t* pal, int colorIdx, uint8_t rgb[3])
 /**
  * Given an R8G8B8 color triplet return the closet matching color index.
  *
+ * @param pal  Color palette.
  * @param rgb  R8G8B8 color to be matched.
+ *
  * @return  Closet matching color index or @c -1 if no colors in the palette.
  */
-int ColorPalette_NearestIndex(colorpalette_t* pal, uint8_t red, uint8_t green, uint8_t blue);
 int ColorPalette_NearestIndexv(colorpalette_t* pal, const uint8_t rgb[3]);
+int ColorPalette_NearestIndex(colorpalette_t* pal, uint8_t red, uint8_t green, uint8_t blue);
 
 #endif /* LIBDENG_REFRESH_COLORPALETTE_H */

doomsday/engine/portable/include/con_main.h

@@ -122,12 +122,20 @@ char* CVar_String(const cvar_t* var);
 Uri* CVar_Uri(const cvar_t* var);
 
 /**
- * \note Also used with @c CVT_BYTE.
- * @param svflags           @see setVariableFlags
+ * Changes the value of an integer variable.
+ * @note Also used with @c CVT_BYTE.
+ *
+ * @param var      Variable.
+ * @param value    New integer value for the variable.
  */
-void CVar_SetInteger2(cvar_t* var, int value, int svflags);
 void CVar_SetInteger(cvar_t* var, int value);
 
+/**
+ * @copydoc CVar_SetInteger()
+ * @param svflags  @ref setVariableFlags
+ */
+void CVar_SetInteger2(cvar_t* var, int value, int svflags);
+
 void CVar_SetFloat2(cvar_t* var, float value, int svflags);
 void CVar_SetFloat(cvar_t* var, float value);
 

doomsday/engine/portable/include/file.h

@@ -1,8 +1,6 @@
 /**
  * @file file.h
- *
  * Base for all classes which represent opened files.
- *
  * @ingroup fs
  *
  * @author Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
@@ -70,8 +68,8 @@ class File1
 public:
     /**
      * @param hndl          Handle to the file. Ownership of the handle is given to this instance.
-     * @param path          Path to this file in the virtual file system.
-     * @param info          Info descriptor for the file. A copy is made.
+     * @param _path         Path to this file in the virtual file system.
+     * @param _info         Info descriptor for the file. A copy is made.
      * @param container     Container of this file. Can be @c NULL.
      */
     File1(FileHandle& hndl, char const* _path, FileInfo const& _info, File1* container = 0);

doomsday/engine/portable/include/fonts.h

@@ -154,12 +154,18 @@ void Fonts_RebuildFromFile(struct font_s* font, const char* resourcePath);
 /**
  * Search the Fonts collection for a font associated with @a uri.
  *
- * @param uri  Either a path or a URN.
+ * @param uri    Either a path or a URN.
+ *
  * @return  Unique identifier of the found texture else @c NOFONTID.
  */
-fontid_t Fonts_ResolveUri2(const Uri* uri, boolean quiet);
 fontid_t Fonts_ResolveUri(const Uri* uri); /*quiet=!(verbose >= 1)*/
 
+/**
+ * @copydoc Fonts_ResolveUri()
+ * @param queit  Suppresses the console message that is printed if the Uri cannot be found.
+ */
+fontid_t Fonts_ResolveUri2(const Uri* uri, boolean quiet);
+
 /// Same as Fonts::ResolveUri except @a uri is a C-string.
 fontid_t Fonts_ResolveUriCString2(const char* uri, boolean quiet);
 fontid_t Fonts_ResolveUriCString(const char* uri); /*quiet=!(verbose >= 1)*/

doomsday/engine/portable/include/gamemap.h

@@ -746,13 +746,20 @@ int GameMap_PathXYTraverse(GameMap* map, coord_t fromX, coord_t fromY, coord_t t
  *       within it (however it is on the same side of the space partition)!
  *
  * @param map  GameMap instance.
- * @param x  X coordinate of the point to test.
- * @param y  Y coordinate of the point to test.
- * @return  BspLeaf instance for that BSP node's leaf.
+ * @param x    X coordinate of the point to test.
+ * @param y    Y coordinate of the point to test.
+ * @return     BspLeaf instance for that BSP node's leaf.
  */
-BspLeaf* GameMap_BspLeafAtPoint(GameMap* map, coord_t const point[2]);
 BspLeaf* GameMap_BspLeafAtPointXY(GameMap* map, coord_t x, coord_t y);
 
+/**
+ * @copybrief    GameMap_BspLeafAtPointXY()
+ * @param map    GameMap instance.
+ * @param point  XY coordinates of the point to test.
+ * @return       BspLeaf instance for that BSP node's leaf.
+ */
+BspLeaf* GameMap_BspLeafAtPoint(GameMap* map, coord_t const point[2]);
+
 /**
  * Private member functions:
  */

doomsday/engine/portable/include/stringarray.h

@@ -113,7 +113,7 @@ void StringArray_Insert(StringArray* ar, const char* str, int atIndex);
 /**
  * Removes the string at position @a index.
  * @param ar  StringArray instance.
- * @param atIndex  Position to remove. When removing position @em n, strings
+ * @param index  Position to remove. When removing position @em n, strings
  *      at positions <i>n+1..last</i> will be pulled to positions <i>n..last-1</i>.
  */
 void StringArray_Remove(StringArray* ar, int index);

doomsday/engine/portable/include/sv_def.h

@@ -63,7 +63,12 @@ void            Sv_Handshake(int playernum, boolean newplayer);
 void            Sv_GetPackets(void);
 
 /**
- * @param flags  @see consolePrintFlags
+ * Sends a console message to one or more clients.
+ *
+ * @param to     Client number to send text to. Use a negative number to
+ *               broadcast to everybody.
+ * @param flags  @ref consolePrintFlags
+ * @param text   Text to send.
  */
 void            Sv_SendText(int to, int flags, const char* text);
 

doomsday/engine/portable/include/sys_network.h

@@ -2,8 +2,6 @@
  * @file sys_network.h
  * Low-level network socket routines. @ingroup network
  *
- * @see @ref sysNetwork
- *
  * @authors Copyright © 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
  * @authors Copyright © 2009-2012 Daniel Swanson <danij@dengine.net>
  *

doomsday/engine/portable/src/blockset.c

@@ -42,7 +42,7 @@ typedef struct blockset_block_s {
 /**
  * Allocate a new block of memory to be used for linear object allocations.
  *
- * @param blockset_t*  Block set into which the new block is added.
+ * @param set  Block set into which the new block is added.
  */
 static void addBlockToSet(blockset_t* set)
 {

doomsday/engine/portable/src/file.cpp

@@ -1,8 +1,6 @@
 /**
- * @file abstractfile.cpp
- *
+ * @file file.cpp
  * Abstract base for all classes which represent loaded files.
- *
  * @ingroup fs
  *
  * @author Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>

doomsday/engine/portable/src/fonts.c

@@ -761,7 +761,6 @@ fontid_t Fonts_ResolveUri2(const Uri* uri, boolean quiet)
     return NOFONTID;
 }
 
-/// @note Part of the Doomsday public API.
 fontid_t Fonts_ResolveUri(const Uri* uri)
 {
     return Fonts_ResolveUri2(uri, !(verbose >= 1)/*log warnings if verbose*/);

doomsday/engine/portable/src/render/rend_font.c

@@ -1178,8 +1178,7 @@ static void freeTextBuffer(void)
     largeTextBufferSize = 0;
 }
 
-/// @note Member of the Doomsday public API.
-void FR_DrawText3(const char* text, const Point2Raw* _origin, int alignFlags, short origTextFlags)
+void FR_DrawText3(const char* text, const Point2Raw* _origin, int alignFlags, short _textFlags)
 {
     fontid_t origFont = FR_Font();
     float cx, cy, extraScale;
@@ -1201,7 +1200,7 @@ void FR_DrawText3(const char* text, const Point2Raw* _origin, int alignFlags, sh
     origin.x = _origin? _origin->x : 0;
     origin.y = _origin? _origin->y : 0;
 
-    origTextFlags &= ~(DTF_INTERNAL_MASK);
+    _textFlags &= ~(DTF_INTERNAL_MASK);
 
     // If we aren't aligning to top-left we need to know the dimensions.
     if(alignFlags & ALIGN_RIGHT)
@@ -1213,8 +1212,8 @@ void FR_DrawText3(const char* text, const Point2Raw* _origin, int alignFlags, sh
     // We need to change the current color, so remember for restore.
     glGetFloatv(GL_CURRENT_COLOR, origColor);
 
-    for(pass = ((origTextFlags & DTF_NO_SHADOW)  != 0? 1 : 0);
-        pass < ((origTextFlags & DTF_NO_GLITTER) != 0? 2 : 3); ++pass)
+    for(pass = ((_textFlags & DTF_NO_SHADOW)  != 0? 1 : 0);
+        pass < ((_textFlags & DTF_NO_GLITTER) != 0? 2 : 3); ++pass)
     {
         // Configure the next pass.
         cx = (float) origin.x;
@@ -1223,9 +1222,9 @@ void FR_DrawText3(const char* text, const Point2Raw* _origin, int alignFlags, sh
         charCount = 0;
         switch(pass)
         {
-        case 0: textFlags = origTextFlags | (DTF_NO_GLITTER|DTF_NO_CHARACTER); break;
-        case 1: textFlags = origTextFlags | (DTF_NO_SHADOW |DTF_NO_GLITTER);   break;
-        case 2: textFlags = origTextFlags | (DTF_NO_SHADOW |DTF_NO_CHARACTER); break;
+        case 0: textFlags = _textFlags | (DTF_NO_GLITTER|DTF_NO_CHARACTER); break;
+        case 1: textFlags = _textFlags | (DTF_NO_SHADOW |DTF_NO_GLITTER);   break;
+        case 2: textFlags = _textFlags | (DTF_NO_SHADOW |DTF_NO_CHARACTER); break;
         }
 
         // Apply defaults.
@@ -1402,13 +1401,11 @@ void FR_DrawText3(const char* text, const Point2Raw* _origin, int alignFlags, sh
     glColor4fv(origColor);
 }
 
-/// @note Member of the Doomsday public API.
 void FR_DrawText2(const char* text, const Point2Raw* origin, int alignFlags)
 {
     FR_DrawText3(text, origin, alignFlags, DEFAULT_DRAWFLAGS);
 }
 
-/// @note Member of the Doomsday public API.
 void FR_DrawText(const char* text, const Point2Raw* origin)
 {
     FR_DrawText2(text, origin, DEFAULT_ALIGNFLAGS);

doomsday/engine/portable/src/sys_audiod_dummy.c

@@ -123,6 +123,8 @@ void DS_DummyShutdown(void)
 /**
  * The Event function is called to tell the driver about certain critical
  * events like the beginning and end of an update cycle.
+ *
+ * @param type  Type of event.
  */
 void DS_DummyEvent(int type)
 {
@@ -162,6 +164,9 @@ void DS_Dummy_SFX_DestroyBuffer(sfxbuffer_t* buf)
  * Prepare the buffer for playing a sample by filling the buffer with as
  * much sample data as fits. The pointer to sample is saved, so the caller
  * mustn't free it while the sample is loaded.
+ *
+ * @param buf     Sound buffer.
+ * @param sample  Sample data.
  */
 void DS_Dummy_SFX_Load(sfxbuffer_t* buf, struct sfxsample_s* sample)
 {
@@ -176,6 +181,8 @@ void DS_Dummy_SFX_Load(sfxbuffer_t* buf, struct sfxsample_s* sample)
 
 /**
  * Stops the buffer and makes it forget about its sample.
+ *
+ * @param buf  Sound buffer.
  */
 void DS_Dummy_SFX_Reset(sfxbuffer_t* buf)
 {
@@ -188,7 +195,8 @@ void DS_Dummy_SFX_Reset(sfxbuffer_t* buf)
 }
 
 /**
- * @return              The length of the buffer in milliseconds.
+ * @param buf  Sound buffer.
+ * @return The length of the buffer in milliseconds.
  */
 unsigned int DS_DummyBufferLength(sfxbuffer_t* buf)
 {
@@ -233,6 +241,7 @@ void DS_Dummy_SFX_Stop(sfxbuffer_t* buf)
 
 /**
  * Buffer streamer. Called by the Sfx refresh thread.
+ * @param buf  Sound buffer.
  */
 void DS_Dummy_SFX_Refresh(sfxbuffer_t* buf)
 {
@@ -249,12 +258,15 @@ void DS_Dummy_SFX_Refresh(sfxbuffer_t* buf)
 }
 
 /**
- * @param prop          SFXBP_VOLUME (if negative, interpreted as attenuation)
- *                      SFXBP_FREQUENCY
- *                      SFXBP_PAN (-1..1)
- *                      SFXBP_MIN_DISTANCE
- *                      SFXBP_MAX_DISTANCE
- *                      SFXBP_RELATIVE_MODE
+ * @param buf   Sound buffer.
+ * @param prop  Buffer property:
+ *              - SFXBP_VOLUME (if negative, interpreted as attenuation)
+ *              - SFXBP_FREQUENCY
+ *              - SFXBP_PAN (-1..1)
+ *              - SFXBP_MIN_DISTANCE
+ *              - SFXBP_MAX_DISTANCE
+ *              - SFXBP_RELATIVE_MODE
+ * @param value Value for the property.
  */
 void DS_Dummy_SFX_Set(sfxbuffer_t* buf, int prop, float value)
 {

doomsday/engine/portable/src/wad.cpp

@@ -1,5 +1,5 @@
 /**
- * @file wadfile.cpp
+ * @file wad.cpp
  * WAD archives. @ingroup fs
  *
  * @author Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>