Documentation: Fixed a bunch of Doxygen errors

Slowly trying to improve the quality of the API documentation...

doomsday/engine/portable/include/abstractresource.h

@@ -60,11 +60,13 @@ void AbstractResource_AddIdentityKey(AbstractResource* resource, const ddstring_
 
 /**
  * Attempt to resolve a path to this resource.
- * @param resource  AbstractResource instance.
+ *
+ * @param r  AbstractResource instance.
+ * @param canLocate  Allow searching for the resource using the relevant search paths.
  *
  * @return  Found path.
  */
-const ddstring_t* AbstractResource_ResolvedPath(AbstractResource* resource, boolean canLocate);
+const ddstring_t* AbstractResource_ResolvedPath(AbstractResource* r, boolean canLocate);
 
 /**
  * Attempt to resolve a path to this resource.
@@ -87,8 +89,9 @@ ddstring_t* AbstractResource_NameStringList(AbstractResource* resource);
 /**
  * Update the "found" status for this resource.
  *
- * @param resource  AbstractResource instance.
+ * @param r  AbstractResource instance.
  * @param yes  @c true = mark as found, else mark not-found.
+ *
  * @return  Same as @a resource for caller convenience.
  */
 AbstractResource* AbstractResource_MarkAsFound(AbstractResource* r, boolean yes);

doomsday/engine/portable/include/audiodriver.h

@@ -46,7 +46,7 @@ void AudioDriver_PrintInterfaces(void);
  * Retrieves the main interface of the audio driver to which @a audioInterface
  * belongs.
  *
- * @param audioInterface  Pointer to a SFX, Music, or CD interface. See
+ * @param anyAudioInterface  Pointer to a SFX, Music, or CD interface. See
  * AudioDriver_SFX(), AudioDriver_Music() and AudioDriver_CD().
  *
  * @return Audio driver interface, or @c NULL if the none of the loaded drivers

doomsday/engine/portable/include/b_command.h

@@ -54,6 +54,20 @@ void         B_DestroyCommandBindingList(evbinding_t* listRoot);
 evbinding_t* B_NewCommandBinding(evbinding_t* listRoot, const char* desc, const char* command);
 void         B_DestroyCommandBinding(evbinding_t* eb);
 void         B_EventBindingToString(const evbinding_t* eb, ddstring_t* str);
-boolean      B_TryCommandBinding(evbinding_t* eb, ddevent_t* event, struct bcontext_s* eventClass);
+
+/**
+ * Checks if the event matches the binding's conditions, and if so, executes the
+ * bound command.
+ *
+ * @param eb          Event binding.
+ * @param event       Event to match against.
+ * @param eventClass  The event has been bound in this binding class. If the
+ *                    bound state is associated with a higher-priority active
+ *                    class, the binding cannot be executed.
+ *
+ * @return  @c true, if the bound command was executed. @c false otherwise, as the
+ *          event didn't match all the conditions.
+ */
+boolean B_TryCommandBinding(evbinding_t* eb, ddevent_t* event, struct bcontext_s* eventClass);
 
 #endif // __DOOMSDAY_BIND_COMMAND_H__

doomsday/engine/portable/include/b_util.h

@@ -79,7 +79,15 @@ void        B_AppendDeviceDescToString(uint device, ddeventtype_t type, int id,
 void        B_AppendToggleStateToString(ebstate_t state, ddstring_t* str);
 void        B_AppendAxisPositionToString(ebstate_t state, float pos, ddstring_t* str);
 void        B_AppendAnglePositionToString(float pos, ddstring_t* str);
+
+/**
+ * Converts a state condition to text string format and appends it to a string.
+ *
+ * @param cond  State condition.
+ * @param str  The condition in textual format is appended here.
+ */
 void        B_AppendConditionToString(const statecondition_t* cond, ddstring_t* str);
+
 void        B_AppendEventToString(const ddevent_t* ev, ddstring_t* str);
 
 #endif // __DOOMSDAY_BIND_UTIL_H__

doomsday/engine/portable/include/binarytree.h

@@ -388,7 +388,7 @@ void* BinaryTree_UserData(BinaryTree* tree);
  * @param tree  BinaryTree instance.
  * @param left  @c true= set the left child.
  *              @c false= set the right child.
- * @param subTree  Ptr to the (child) tree to be linked or @c NULL.
+ * @param subtree  Ptr to the (child) tree to be linked or @c NULL.
  */
 BinaryTree* BinaryTree_SetChild(BinaryTree* tree, boolean left, BinaryTree* subtree);
 

doomsday/engine/portable/include/blockmap.h

@@ -60,14 +60,15 @@ const AABoxd* Blockmap_Bounds(Blockmap* blockmap);
 BlockmapCoord Blockmap_Width(Blockmap* blockmap);
 
 /**
- * @param blockmap      Blockmap instance.
+ * @param blockmap  Blockmap instance.
  * @return  Height of the Blockmap in cells.
  */
 BlockmapCoord Blockmap_Height(Blockmap* blockmap);
 
 /**
  * Retrieve the size of the Blockmap in cells.
  *
+ * @param blockmap     Blockmap instance.
  * @param widthHeight  Size of the Blockmap [width,height] written here.
  */
 void Blockmap_Size(Blockmap* blockmap, BlockmapCoord widthHeight[2]);

doomsday/engine/portable/include/cbuffer.h

@@ -78,6 +78,7 @@ void CBuffer_Delete(CBuffer* cb);
 /**
  * Write the given text string (plus optional flags) to the buffer.
  *
+ * @param cb   Console buffer.
  * @param flags  @see consoleBufferLineFlags
  * @param txt  Ptr to the text string to be written.
  */
@@ -93,8 +94,10 @@ void CBuffer_Clear(CBuffer* cb);
 uint CBuffer_MaxLineLength(CBuffer* cb);
 
 /**
- * Change the maximum line length.
- * \note Existing lines are unaffected, the change only impacts new lines.
+ * Change the maximum line length. @note The existing lines are unaffected, the
+ * change only impacts new lines.
+ *
+ * @param cb      Console buffer.
  * @param length  New max line length, in characters.
  */
 void CBuffer_SetMaxLineLength(CBuffer* cb, uint length);
@@ -105,7 +108,9 @@ uint CBuffer_NumLines(CBuffer* cb);
 /**
  * Retrieve an immutable ptr to the text line at index @a idx.
  *
+ * @param cb   Console buffer.
  * @param idx  Index of the line to retrieve.
+ *
  * @return  Text line at index @a idx, or @c NULL if invalid index.
  */
 const cbline_t* CBuffer_GetLine(CBuffer* cb, uint idx);

doomsday/engine/portable/include/cl_player.h

@@ -62,14 +62,16 @@ void            Cl_InitPlayers(void);
  * Used in DEMOS. (Not in regular netgames.)
  * Applies the given dx and dy to the local player's coordinates.
  *
- * @param z             Absolute viewpoint height.
+ * @param dx            Viewpoint X delta.
+ * @param dy            Viewpoint Y delta.
+ * @param z             Viewpoint absolute Z coordinate.
  * @param onground      If @c true the mobj's Z will be set to floorz, and
  *                      the player's viewheight is set so that the viewpoint
  *                      height is param 'z'.
  *                      If @c false the mobj's Z will be param 'z' and
  *                      viewheight is zero.
  */
-void ClPlayer_MoveLocal(coord_t dx, coord_t dy, coord_t dz, boolean onground);
+void ClPlayer_MoveLocal(coord_t dx, coord_t dy, coord_t z, boolean onground);
 
 void ClPlayer_UpdateOrigin(int plrnum);
 

doomsday/engine/portable/include/colorpalette.h

@@ -48,10 +48,12 @@ typedef struct colorpalette_s {
 colorpalette_t* ColorPalette_New(void);
 
 /**
+ * Constructs a new color palette.
+ *
  * @param compOrder  Component order. Examples:
- *      [0,1,2] == RGB
- *      [2,1,0] == BGR
- * @param compSize  Number of bits per component [R,G,B].
+ * <pre> [0,1,2] == RGB
+ * [2,1,0] == BGR</pre>
+ * @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.
  */
@@ -66,9 +68,10 @@ ushort ColorPalette_Size(colorpalette_t* pal);
 /**
  * Replace the entire color table.
  *
+ * @param pal  Color palette.
  * @param compOrder  Component order. Examples:
- *      [0,1,2] == RGB
- *      [2,1,0] == BGR
+ * <pre> [0,1,2] == RGB
+ * [2,1,0] == BGR</pre>
  * @param compSize  Number of bits per component [R,G,B].
  * @param colorData  Color triplets (at least @a numColors * 3).
  * @param colorCount  Number of color triplets.
@@ -79,9 +82,10 @@ void ColorPalette_ReplaceColorTable(colorpalette_t* pal, const int compOrder[3],
 /**
  * Lookup a color in the palette.
  *
- * \note If the specified color index is out of range it will be clamped to
+ * @note If the specified color index is out of range it will be clamped to
  * a valid value before use.
  *
+ * @param pal  Color palette.
  * @param colorIdx  Index of the color to lookup.
  * @param rgb  Associated R8G8B8 color triplet is written here.
  */

doomsday/engine/portable/include/con_main.h

@@ -338,12 +338,16 @@ const knownword_t** Con_CollectKnownWordsMatchingWord(const char* word,
 
 /**
  * Print a 'global' message (to stdout and the console).
+ *
+ * @param message  Message with printf() formatting syntax for arguments.
  */
 void Con_Message(const char* message, ...) PRINTF_F(1,2);
 
 /**
  * Print into the console.
- * @param flags  @see consolePrintFlags
+ *
+ * @param flags   @see consolePrintFlags
+ * @param format  Format for the output using printf() formatting syntax.
  */
 void Con_FPrintf(int flags, const char* format, ...) PRINTF_F(2,3);
 void Con_Printf(const char* format, ...) PRINTF_F(1,2);
@@ -365,10 +369,12 @@ void Con_PrintRuler(void);
 /**
  * Prints the passed path list to the console.
  *
- * \todo treat paths as URIs (i.e., resolve symbols).
+ * @todo treat paths as URIs (i.e., resolve symbols).
  *
- * @param pathList  A series of file/resource names/paths separated by @a delimiter.
- * @param flags @see printPathFlags.
+ * @param pathList   A series of file/resource names/paths separated by @a delimiter.
+ * @param delimiter  Path delimiter character.
+ * @param separator  Text printed between list entries.
+ * @param flags      @see printPathFlags.
  */
 void Con_PrintPathList4(const char* pathList, char delimiter, const char* separator, int flags);
 void Con_PrintPathList3(const char* pathList, char delimiter, const char* separator); /* flags = DEFAULT_PRINTPATHFLAGS */

doomsday/engine/portable/include/dd_games.h

@@ -174,7 +174,7 @@ namespace de
 extern "C" {
 #endif
 
-/**
+/*
  * C wrapper API:
  */
 
@@ -191,12 +191,21 @@ int GameCollection_Count(GameCollection* games);
 int GameCollection_NumPlayable(GameCollection* games);
 
 /**
- * @param game  Game instance.
- * @return Unique identifier associated with @a game.
+ * Returns the unique identifier associated with @a game.
+ *
+ * @param games  Game collection.
+ * @param game   Game instance.
+ *
+ * @return Game identifier.
  */
 gameid_t GameCollection_Id(GameCollection* games, Game* game);
 
 /**
+ * Finds a game with a particular identifier in the game collection.
+ *
+ * @param games   Game collection.
+ * @param gameId  Game identifier (see GameCollection_Id()).
+ *
  * @return  Game associated with @a gameId else @c NULL.
  */
 Game* GameCollection_ById(GameCollection* games, gameid_t gameId);
@@ -207,15 +216,30 @@ Game* GameCollection_ById(GameCollection* games, gameid_t gameId);
 Game* GameCollection_ByIdentityKey(GameCollection* games, char const* identityKey);
 
 /**
+ * Locates a game in the collection.
+ *
+ * @param games  Game collection.
+ * @param idx    Index of the game in the collection. Valid indices
+ *               are in the range 0 ... GameCollection_Count() - 1.
+ *
  * @return  Game associated with unique index @a idx else @c NULL.
  */
 Game* GameCollection_ByIndex(GameCollection* games, int idx);
 
-/// @return The first playable game in the collection according to registration order.
+/**
+ * Finds the first playable game in the collection according to registration
+ * order.
+ *
+ * @param games  Game collection.
+ *
+ * @return Game instance.
+ */
 Game* GameCollection_FirstPlayable(GameCollection* games);
 
 /**
  * Try to locate all startup resources for all registered games.
+ *
+ * @param games  Game collection.
  */
 void GameCollection_LocateAllResources(GameCollection* games);
 

doomsday/engine/portable/include/map/bsp/superblockmap.h

@@ -239,7 +239,7 @@ class SuperBlock
 
     const HEdges& hedges() const;
 
-    DENG_DEBUG_ONLY(
+#ifdef DENG_DEBUG
     static void DebugPrint(SuperBlock const& inst)
     {
         DENG2_FOR_EACH_CONST(SuperBlock::HEdges, it, inst.hedges())
@@ -251,7 +251,8 @@ class SuperBlock
                 << hedge->v[0]->origin[VX] << hedge->v[0]->origin[VY]
                 << hedge->v[1]->origin[VX] << hedge->v[1]->origin[VY];
         }
-    })
+    }
+#endif
 
 private:
     /**

doomsday/engine/portable/include/pathdirectory.h

@@ -134,7 +134,7 @@ class PathDirectoryNode
      */
     ddstring_t* composePath(ddstring_t* path, int* length, char delimiter = '/') const;
 
-    /// @fixme should be private:
+    /// @todo FIXME: should be private:
     StringPoolId internId() const;
 
 private:
@@ -294,7 +294,7 @@ class PathDirectory
     static void debugPrintHashDistribution(PathDirectory& pd);
 #endif
 
-    /// @fixme Should be private:
+    /// @todo FIXME: Should be private:
     ushort hashForInternId(StringPoolId internId);
 
 private:

doomsday/engine/portable/src/b_command.c

@@ -384,17 +384,6 @@ void B_SubstituteInCommand(const char* command, ddevent_t* event, evbinding_t* e
     }
 }
 
-/**
- * Checks if the event matches the binding's conditions, and if so, executes the
- * bound command.
- *
- * @param eventClass  The event has been bound in this binding class. If the
- *                    bound state is associated with a higher-priority active
- *                    class, the binding cannot be executed.
- *
- * @return  @c true, if the bound command was executed. @c false otherwise, as the
- *          event didn't match all the conditions.
- */
 boolean B_TryCommandBinding(evbinding_t* eb, ddevent_t* event, struct bcontext_s* eventClass)
 {
     int         i;

doomsday/engine/portable/src/b_util.c

@@ -585,9 +585,6 @@ void B_AppendAnglePositionToString(float pos, ddstring_t* str)
         Str_Appendf(str, "-angle%g", pos);
 }
 
-/**
- * @param str  The condition in textual format is appended here.
- */
 void B_AppendConditionToString(const statecondition_t* cond, ddstring_t* str)
 {
     if(cond->type == SCT_STATE)
@@ -630,6 +627,7 @@ void B_AppendConditionToString(const statecondition_t* cond, ddstring_t* str)
 }
 
 /**
+ * @param ev  Event.
  * @param str  The event in textual format is appended here.
  */
 void B_AppendEventToString(const ddevent_t* ev, ddstring_t* str)

doomsday/engine/portable/src/map/entitydatabase.cpp

@@ -1,5 +1,5 @@
 /**
- * @file mapentitydatabase.cpp
+ * @file entitydatabase.cpp
  * Database of map entity property values. @ingroup map
  *
  * @author Copyright &copy; 2007-2012 Daniel Swanson <danij@dengine.net>

doomsday/engine/portable/src/resource/texture.cpp

@@ -1,5 +1,5 @@
 /**
- * @file texture.c
+ * @file texture.cpp
  * Logical texture. @ingroup resource
  *
  * @authors Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>

doomsday/engine/portable/src/resource/texturevariant.cpp

@@ -1,5 +1,5 @@
 /**
- * @file texturevariant.c
+ * @file texturevariant.cpp
  * Logical texture variant. @ingroup resource
  *
  * @authors Copyright &copy; 2012 Daniel Swanson <danij@dengine.net>