Documentation: Fixed a bunch of Doxygen warnings

doomsday/engine/api/dd_fontrenderer.h

@@ -188,8 +188,7 @@ int FR_TextHeight(const char* text);
  * Draw a character.
  *
  * @param ch  Character to be drawn.
- * @param x  X origin/offset at which to begin drawing.
- * @param y  Y origin/offset at which to begin drawing.
+ * @param origin  Origin/offset at which to begin drawing.
  * @param alignFlags  @ref alignmentFlags
  * @param flags  @ref drawTextFlags
  */

doomsday/engine/api/dd_string.h

@@ -253,7 +253,7 @@ const char* Str_GetLine(ddstring_t* ds, const char* src);
  * @param dest          Destination string.
  * @param src           Source string.
  * @param delimiter     Delimiter character.
- * @param flags         @ref copyDelimiterFlags
+ * @param cdflags       @ref copyDelimiterFlags
  *
  * @return              Pointer to the character within @a src where copy stopped
  *                      else @c NULL if the end was reached.
@@ -311,7 +311,7 @@ ddstring_t* Str_PercentEncode(ddstring_t* str);
  *                      @a excludeChars). @c 0 terminated.
  * @return              Same as @a str.
  */
-ddstring_t* Str_PercentEncode2(ddstring_t* str, const char* excludeChars, const char* includeCars);
+ddstring_t* Str_PercentEncode2(ddstring_t* str, const char* excludeChars, const char* includeChars);
 
 /**
  * Decode the percent-encoded string. Will match codes for the unicode

doomsday/engine/api/reader.h

@@ -1,5 +1,5 @@
 /**
- * @file reader.h
+ * @file api/reader.h
  * Deserializer for reading values and data from a byte array.
  *
  * @ingroup base

doomsday/engine/api/stringpool.h

@@ -218,9 +218,9 @@ boolean StringPool_RemoveById(StringPool* pool, StringPoolId id);
  * Iterate over all strings in the pool making a callback for each. Iteration
  * ends when all strings have been processed or a callback returns non-zero.
  *
- * @param pool  StringPool instance.
+ * @param pool      StringPool instance.
  * @param callback  Callback to make for each iteration.
- * @param parameters  User data to be passed to the callback.
+ * @param data      User data to be passed to the callback.
  *
  * @return  @c 0 iff iteration completed wholly. Otherwise the non-zero value returned
  *          by @a callback.

doomsday/engine/api/uri.h

@@ -75,9 +75,9 @@ Uri* Uri_New(void);
  * Constructs a Uri instance from @a path. The uri should be destroyed with
  * Uri_Delete() once it is no longer needed.
  *
- * @param path           Path to be parsed. Assumed to be in percent-encoded representation.
- * @param resourceClass  If no scheme is defined in @a path and this is not @c RC_NULL,
- *                       look for an appropriate default scheme for this class of resource.
+ * @param path  Path to be parsed. Assumed to be in percent-encoded representation.
+ * @param defaultResourceClass  If no scheme is defined in @a path and this is not @c RC_NULL,
+ *      look for an appropriate default scheme for this class of resource.
  */
 Uri* Uri_NewWithPath2(const char* path, resourceclass_t defaultResourceClass);
 Uri* Uri_NewWithPath(const char* path);
@@ -151,12 +151,14 @@ const ddstring_t* Uri_Scheme(const Uri* uri);
 const ddstring_t* Uri_Path(const Uri* uri);
 
 /**
- * @param path  New scheme to be parsed.
+ * @param uri     Uri instance.
+ * @param scheme  New scheme to be parsed.
  * @return  Same as @a uri, for caller convenience.
  */
 Uri* Uri_SetScheme(Uri* uri, const char* scheme);
 
 /**
+ * @param uri   Uri instance.
  * @param path  New path to be parsed.
  * @return  Same as @a uri, for caller convenience.
  */
@@ -165,10 +167,11 @@ Uri* Uri_SetPath(Uri* uri, const char* path);
 /**
  * Update uri by parsing new values from the specified arguments.
  *
- * @param uri            Uri instance.
- * @param path           Path to be parsed. Assumed to be in percent-encoded representation.
- * @param resourceClass  If no scheme is defined in @a path and this is not @c RC_NULL,
- *                       look for an appropriate default scheme for this class of resource.
+ * @param uri   Uri instance.
+ * @param path  Path to be parsed. Assumed to be in percent-encoded representation.
+ * @param defaultResourceClass  If no scheme is defined in @a path and this is not
+ *              @c RC_NULL, look for an appropriate default scheme for this class
+ *              of resource.
  *
  * @return  Same as @a uri, for caller convenience.
  */
@@ -215,6 +218,7 @@ boolean Uri_Equality(const Uri* uri, const Uri* other);
  * @note Scheme should only be omitted when it can be unambiguously deduced from context.
  *
  * @param uri  Uri instance.
+ * @param writer  Writer instance.
  * @param omitComponents  @ref uriComponentFlags
  */
 void Uri_Write2(const Uri* uri, Writer* writer, int omitComponents);

doomsday/engine/api/writer.h

@@ -1,5 +1,5 @@
 /**
- * @file writer.h
+ * @file api/writer.h
  * Serializer for writing values and data into a byte array.
  *
  * @ingroup base

doomsday/engine/portable/include/abstractresource.h

@@ -1,4 +1,4 @@
-/**\file resourceresourceord.h
+/**\file abstractresource.h
  *\section License
  * License: GPL
  * Online License Link: http://www.gnu.org/licenses/gpl.html

doomsday/engine/portable/include/concurrency.h

@@ -36,6 +36,10 @@ typedef void* sem_t;
 
 #include <QThread>
 
+/**
+ * Thread that runs a user-specified callback function. Exceptions from the callback
+ * function are caught.
+ */
 class CallbackThread : public QThread
 {
     Q_OBJECT

doomsday/engine/portable/include/def_data.h

@@ -25,7 +25,7 @@
 /**
  * Engine Definition Files
  *
- * \fixme Needs to be redesigned.
+ * @todo Needs to be redesigned.
  */
 
 #ifndef LIBDENG_DEFINITION_FILE_H

doomsday/engine/portable/include/lumpfile.h

@@ -1,4 +1,4 @@
-/**\file lumpfile_h
+/**\file lumpfile.h
  *\section License
  * License: GPL
  * Online License Link: http://www.gnu.org/licenses/gpl.html

doomsday/engine/portable/include/masterserver.h

@@ -102,7 +102,7 @@ void N_MasterAnnounceServer(boolean isOpen);
 void N_MasterRequestList(void);
 
 /**
- * Returns information about the server #N.
+ * Returns information about the server @em N.
  *
  * @return @c 0, if communication with the master is currently in progress. If
  * param info is @c NULL, will return the number of known servers ELSE, will

doomsday/engine/portable/include/p_particle.h

@@ -1,5 +1,5 @@
 /**
- * @file particle.h
+ * @file p_particle.h
  * Generator (particles) management. @ingroup map
  *
  * @authors Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>

doomsday/engine/portable/src/bspleaf.cpp

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

doomsday/engine/portable/src/con_busy.c

@@ -670,7 +670,7 @@ lineIsNotNew:;
 
 /**
  * Draws a number of console output to the bottom of the screen.
- * \fixme: Wow. I had some weird time hacking the smooth scrolling. Cleanup would be
+ * @todo: Wow. I had some weird time hacking the smooth scrolling. Cleanup would be
  *         good some day. -jk
  */
 void Con_BusyDrawConsoleOutput(void)

doomsday/engine/portable/src/con_main.c

@@ -992,7 +992,7 @@ static int executeSubCmd(const char *subCmd, byte src, boolean isNetCmd)
                     CVar_SetString(cvar, argptr);
                     break;
                 case CVT_URIPTR: {
-                    /// \fixme Sanitize and validate against known schemas.
+                    /// @todo Sanitize and validate against known schemas.
                     Uri* uri = Uri_NewWithPath2(argptr, RC_NULL);
                     CVar_SetUri(cvar, uri);
                     Uri_Delete(uri);

doomsday/engine/portable/src/def_data.c

@@ -25,7 +25,7 @@
 /**
  * Doomsday Engine Definition Files
  *
- * \fixme Needs to be redesigned.
+ * @todo Needs to be redesigned.
  */
 
 #include <stdio.h>

doomsday/engine/portable/src/def_main.c

@@ -1981,7 +1981,7 @@ StringArray* Def_ListStateIDs(void)
 
 /**
  * Prints a list of all the registered mobjs to the console.
- * \fixme Does this belong here?
+ * @todo Does this belong here?
  */
 D_CMD(ListMobjs)
 {

doomsday/engine/portable/src/dfile.c

@@ -1,4 +1,4 @@
-/**\file filehandle.c
+/**\file dfile.c
  *\section License
  * License: GPL
  * Online License Link: http://www.gnu.org/licenses/gpl.html

doomsday/engine/portable/src/edit_bsp.cpp

@@ -1,5 +1,5 @@
 /**
- * @file bsp_map.c
+ * @file bsp_map.cpp
  * BSP Builder. @ingroup map
  *
  * @authors Copyright © 2006-2012 Daniel Swanson <danij@dengine.net>

doomsday/engine/portable/src/edit_map.c

@@ -444,7 +444,7 @@ void MPE_PruneRedundantMapData(editmap_t* map, int flags)
 {
 #if 0
     /**
-     * \fixme Pruning cannot be done as game map data object properties
+     * @todo Pruning cannot be done as game map data object properties
      * are currently indexed by their original indices as determined by the
      * position in the map data. The same problem occurs within ACS scripts
      * and XG line/sector references.

doomsday/engine/portable/src/fs_main.c

@@ -595,7 +595,7 @@ int F_Reset(void)
 #endif
 
     // Reset file IDs so previously seen files can be processed again.
-    /// \fixme this releases the ID of startup files too but given the
+    /// @todo this releases the ID of startup files too but given the
     /// only startup file is doomsday.pk3 which we never attempt to load
     /// again post engine startup, this isn't an immediate problem.
     F_ResetFileIds();

doomsday/engine/portable/src/fs_util.c

@@ -46,7 +46,7 @@
 
 void F_FileDir(ddstring_t* dst, const ddstring_t* src)
 {
-    /// \fixme Potentially truncates @a src to FILENAME_T_MAXLEN
+    /// @todo Potentially truncates @a src to FILENAME_T_MAXLEN
     directory_t* dir = Dir_ConstructFromPathDir(Str_Text(src));
     Str_Set(dst, Dir_Path(dir));
     Dir_Delete(dir);
@@ -568,7 +568,7 @@ const char* F_PrettyPath(const char* path)
 {
 #define NUM_BUFS            8
 
-    static ddstring_t buffers[NUM_BUFS]; // \fixme: never free'd!
+    static ddstring_t buffers[NUM_BUFS]; // @todo: never free'd!
     static uint index = 0;
     ddstring_t* buf = NULL;
     int len;

doomsday/engine/portable/src/game.c

@@ -1,4 +1,4 @@
-/**\file gameinfo.c
+/**\file game.c
  *\section License
  * License: GPL
  * Online License Link: http://www.gnu.org/licenses/gpl.html

doomsday/engine/portable/src/gl_main.c

@@ -878,7 +878,7 @@ void GL_SetMaterialUI2(material_t* mat, int wrapS, int wrapT)
     const materialvariantspecification_t* spec;
     const materialsnapshot_t* ms;
 
-    if(!mat) return; // \fixme we need a "NULL material".
+    if(!mat) return; // @todo we need a "NULL material".
 
     spec = Materials_VariantSpecificationForContext(MC_UI, 0, 1, 0, 0,
         wrapS, wrapT, 0, 1, 0, false, false, false, false);
@@ -896,7 +896,7 @@ void GL_SetPSprite(material_t* mat, int tClass, int tMap)
     const materialvariantspecification_t* spec;
     const materialsnapshot_t* ms;
 
-    if(!mat) return; // \fixme we need a "NULL material".
+    if(!mat) return; // @todo we need a "NULL material".
 
     spec = Materials_VariantSpecificationForContext(MC_PSPRITE, 0, 1, tClass,
         tMap, GL_CLAMP_TO_EDGE, GL_CLAMP_TO_EDGE, 0, 1, 0, false, true, true, false);

doomsday/engine/portable/src/gl_pcx.c

@@ -48,7 +48,7 @@ typedef struct {
 } header_t;
 #pragma pack()
 
-static char* lastErrorMsg = 0; /// \fixme potentially never free'd
+static char* lastErrorMsg = 0; /// @todo potentially never free'd
 
 static void setLastError(const char* msg)
 {

doomsday/engine/portable/src/gl_png.c

@@ -31,7 +31,7 @@
 #include "de_graphics.h"
 #include "m_misc.h"
 
-static char* lastErrorMsg = 0; /// \fixme potentially never free'd
+static char* lastErrorMsg = 0; /// @todo potentially never free'd
 
 static void setLastError(const char* msg)
 {
@@ -152,7 +152,7 @@ uint8_t* PNG_Load(DFile* file, int* width, int* height, int* pixelSize)
                             *pixelSize = 4; // With alpha channel.
 
                         // OK, let's copy it into Doomsday's buffer.
-                        // \fixme Why not load directly into it?
+                        // @todo Why not load directly into it?
                         retbuf = M_Malloc(4 * png_get_image_width(png_ptr, png_info) *
                                           png_get_image_height(png_ptr, png_info));
                         rows = png_get_rows(png_ptr, png_info);

doomsday/engine/portable/src/gl_tex.c

@@ -55,7 +55,7 @@ static uint8_t* GetScratchBuffer(size_t size)
  * pixel, or rather the number of bytes per pixel (3 or 4). The strides must
  * be byte-aligned anyway, though; not in pixels.
  *
- * \fixme Probably could be optimized.
+ * @todo Probably could be optimized.
  */
 static void scaleLine(const uint8_t* in, int inStride, uint8_t* out, int outStride,
     int outLen, int inLen, int comps)

doomsday/engine/portable/src/gl_texmanager.c

@@ -1015,7 +1015,7 @@ static uploadcontentmethod_t prepareVariantFromImage(TextureVariant* tex, image_
      * coordinates are calculated as width/CeilPow2(width), or 1 if larger
      * than the maximum texture size.
      *
-     * \fixme Image dimensions may not be the same as the final uploaded texture!
+     * @todo Image dimensions may not be the same as the final uploaded texture!
      */
     if((flags & TXCF_UPLOAD_ARG_NOSTRETCH) &&
        (!GL_state.features.texNonPowTwo || spec->mipmapped))
@@ -2276,7 +2276,7 @@ static void loadDoomPatch(uint8_t* buffer, int texwidth, int texheight,
 
                     if(trans >= 0)
                     {
-                        /// \fixme Check bounds!
+                        /// @todo Check bounds!
                         palidx = *(translationTables + trans + palidx);
                     }
 
@@ -2333,7 +2333,7 @@ TexSource GL_LoadDetailTextureLump(image_t* image, DFile* file)
         GL_InitImage(image);
 
         /**
-         * \fixme Do not fatal error here if the not a known format!
+         * @todo Do not fatal error here if the not a known format!
          * Perform this check much earlier, when the definitions are
          * read and mark which are valid.
          */
@@ -2383,7 +2383,7 @@ TexSource GL_LoadFlatLump(image_t* image, DFile* file)
 
         GL_InitImage(image);
 
-        /// \fixme not all flats are 64x64!
+        /// @todo not all flats are 64x64!
         image->size.width  = FLAT_WIDTH;
         image->size.height = FLAT_HEIGHT;
         image->pixelSize = 1;

doomsday/engine/portable/src/gl_tga.c

@@ -78,7 +78,7 @@ typedef struct {
 } tga_imagespec_t;
 #pragma pack()
 
-static char* lastErrorMsg = 0; /// \fixme potentially never free'd
+static char* lastErrorMsg = 0; /// @todo potentially never free'd
 
 #ifdef __BIG_ENDIAN__
 static int16_t shortSwap(int16_t n)

doomsday/engine/portable/src/material.c

@@ -213,7 +213,7 @@ boolean Material_HasGlow(material_t* mat)
     if(novideo) return false;
 
     {
-    /// \fixme We should not need to prepare to determine this.
+    /// @todo We should not need to prepare to determine this.
     const materialvariantspecification_t* spec = Materials_VariantSpecificationForContext(
         MC_MAPSURFACE, 0, 0, 0, 0, GL_REPEAT, GL_REPEAT, -1, -1, -1, true, true, false, false);
     const materialsnapshot_t* ms = Materials_Prepare(mat, spec, true);

doomsday/engine/portable/src/materials.c

@@ -1718,7 +1718,7 @@ boolean Materials_HasDecorations(material_t* mat)
     if(novideo) return false;
 
     assert(mat);
-    /// \fixme We should not need to prepare to determine this.
+    /// @todo We should not need to prepare to determine this.
     /// Nor should we need to process the group each time. Cache this decision.
     if(Materials_DecorationDef(mat)) return true;
     if(Material_IsGroupAnimated(mat))

doomsday/engine/portable/src/p_data.c

@@ -1,5 +1,5 @@
 /**
- * @file p_data.h
+ * @file p_data.c
  * Playsim Data Structures. @ingroup play
  *
  * @authors Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>

doomsday/engine/portable/src/p_particle.c

@@ -1,5 +1,5 @@
 /**
- * @file particle.c
+ * @file p_particle.c
  * Generator (particles) management. @ingroup map
  *
  * @authors Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>