Documentation: Replacing unknown Doxygen tags and fixing errors

Unknown tags are replaced with closest-matching Doxygen tags.

doomsday/engine/portable/include/abstractfile.h

@@ -70,27 +70,39 @@ typedef struct abstractfile_s {
 /**
  * Initialize this resource.
  *
+ * @param af    AbstractFile instance.
  * @param type  File type identifier.
  * @param path  Path to this file in the virtual file system.
  * @param file  Handle to the file. AbstractFile takes ownership of the handle.
  * @param info  Lump info descriptor for the file. A copy is made.
- * @return  Same as @a af for convenience (chaining).
+ *
+ * @return  @a af for convenience (chaining).
  */
 abstractfile_t* AbstractFile_Init(abstractfile_t* af, filetype_t type,
     const char* path, DFile* file, const LumpInfo* info);
 
 /**
  * Release all memory acquired for objects linked with this resource.
+ * @param af    AbstractFile instance.
  */
 void AbstractFile_Destroy(abstractfile_t* af);
 
-/// @return  Type of this resource @see filetype_t
+/**
+ * @param af    AbstractFile instance.
+ * @return  Type of this resource @see filetype_t
+ */
 filetype_t AbstractFile_Type(const abstractfile_t* af);
 
-/// @return  Immutable copy of the info descriptor for this resource.
+/**
+ * @param af    AbstractFile instance.
+ * @return  Immutable copy of the info descriptor for this resource.
+ */
 const LumpInfo* AbstractFile_Info(abstractfile_t* af);
 
-/// @return  Owning package else @c NULL if not contained.
+/**
+ * @param af    AbstractFile instance.
+ * @return  Owning package else @c NULL if not contained.
+ */
 abstractfile_t* AbstractFile_Container(const abstractfile_t* af);
 
 /**

doomsday/engine/portable/include/abstractresource.h

@@ -42,19 +42,22 @@ void AbstractResource_Delete(AbstractResource* resource);
 /**
  * Add a new symbolic name to the list of names for this.
  *
+ * @param resource  AbstractResource instance.
  * @param name  New name for this resource. Newer names have precedence.
  */
 void AbstractResource_AddName(AbstractResource* resource, const ddstring_t* name);
 
 /**
  * Add a new sub-resource identity key to the list for this.
  *
+ * @param resource  AbstractResource instance.
  * @param identityKey  New identity key (e.g., a lump/file name).
  */
 void AbstractResource_AddIdentityKey(AbstractResource* resource, const ddstring_t* identityKey);
 
 /**
  * Attempt to resolve a path to this resource.
+ * @param resource  AbstractResource instance.
  *
  * @return  Found path.
  */

doomsday/engine/portable/include/filedirectory.h

@@ -84,6 +84,7 @@ void FileDirectory_Clear(FileDirectory* fd);
 /**
  * Resolve and collate all paths in the directory into a list.
  *
+ * @param fd    FileDirectory instance.
  * @param type  If a valid type, only paths of this type will be visited.
  * @param count  Number of visited paths is written back here.
  *
@@ -95,6 +96,7 @@ ddstring_t* FileDirectory_AllPaths(FileDirectory* fd, pathdirectorynode_type_t t
 /**
  * Add a new set of paths. Duplicates are automatically pruned.
  *
+ * @param fd    FileDirectory instance.
  * @param flags  @see searchPathFlags
  * @param paths  One or more paths.
  * @param pathsCount  Number of elements in @a paths.
@@ -110,6 +112,7 @@ void FileDirectory_AddPaths(FileDirectory* fd,  int flags, const Uri* const* pat
 /**
  * Add a new set of paths from a path list. Duplicates are automatically pruned.
  *
+ * @param fd    FileDirectory instance.
  * @param flags  @see searchPathFlags
  * @param pathList  One or more paths separated by semicolons.
  * @param callback  Callback function ptr.
@@ -124,6 +127,7 @@ void FileDirectory_AddPathList(FileDirectory* fd, int flags, const char* pathLis
 /**
  * Find a path in the directory.
  *
+ * @param fd    FileDirectory instance.
  * @param type  If a valid path type only consider nodes of this type.
  * @param searchPath  Relative or absolute path.
  * @param searchDelimiter  Fragments of @a searchPath are delimited by this character.
@@ -139,6 +143,7 @@ boolean FileDirectory_Find(FileDirectory* fd, pathdirectorynode_type_t type,
  * Iterate over nodes in the directory making a callback for each.
  * Iteration ends when all nodes have been visited or a callback returns non-zero.
  *
+ * @param fd    FileDirectory instance.
  * @param type  If a valid path type only process nodes of this type.
  * @param parent  If not @c NULL, only process child nodes of this node.
  * @param callback  Callback function ptr.

doomsday/engine/portable/include/filelist.h

@@ -118,7 +118,7 @@ DFile* FileList_RemoveFront(FileList* fl);
 DFile* FileList_RemoveBack(FileList* fl);
 
 /**
- * Remove file reference at position @idx.
+ * Remove file reference at position @a idx.
  *
  * @param idx  Index of the reference to be removed. Negative indexes allowed.
  * @return  Ptr to file referenced by the removed node if successful else @c NULL.

doomsday/engine/portable/include/fs_util.h

@@ -157,7 +157,7 @@ boolean F_MakeAbsolute(ddstring_t* dst, const ddstring_t* src);
 boolean F_TranslatePath(ddstring_t* dst, const ddstring_t* src);
 
 /**
- * @important Not thread-safe!
+ * @warning Not thread-safe!
  * @return  A prettier copy of the original path.
  */
 const char* F_PrettyPath(const char* path);

doomsday/engine/portable/include/gl_tex.h

@@ -96,7 +96,7 @@ void ColorOutlinesIdx(uint8_t* pixels, int width, int height);
 void Desaturate(uint8_t* pixels, int width, int height, int pixelSize);
 
 /**
- * @important Does not conform to any standard technique and adjustments
+ * @note Does not conform to any standard technique and adjustments
  * are applied symmetrically for all color components.
  *
  * @param pixels  RGB(a) image to be enhanced.
@@ -110,7 +110,8 @@ void EnhanceContrast(uint8_t* pixels, int width, int height, int pixelSize);
  * Equalize the specified luminance map such that the minimum and maximum
  * brightness covers the whole [0...255] range.
  *
- * @algorithm Calculates shift deltas for bright and dark-side pixels by
+ * @par Algorithm
+ * Calculates shift deltas for bright and dark-side pixels by
  * averaging the luminosity of all pixels in the original image.
  *
  * @param pixels  Luminance image to equalize.
@@ -183,7 +184,9 @@ void FindAverageAlphaIdx(const uint8_t* pixels, int width, int height,
 
 /**
  * Calculates a clip region for the image that excludes alpha pixels.
- * @algorithm: Cross spread from bottom > top, right > left (inside out).
+ *
+ * @par Algorithm
+ * Cross spread from bottom > top, right > left (inside out).
  *
  * @param pixels  Image data to be processed.
  * @param width  Width of the image in pixels.

doomsday/engine/portable/include/p_maputil.h

@@ -127,7 +127,7 @@ void P_MobjLink(mobj_t* mo, byte flags);
 int P_MobjUnlink(mobj_t* mo);
 
 /**
- * @important Caller must ensure that the mobj is currently unlinked.
+ * @note Caller must ensure that the mobj is currently unlinked.
  */
 void P_LinkMobjToLineDefs(mobj_t* mo);
 

doomsday/engine/portable/include/r_lumobjs.h

@@ -198,7 +198,7 @@ int LO_LumobjsRadiusIterator(BspLeaf* bspLeaf, coord_t x, coord_t y, coord_t rad
  * Project all lights affecting the given quad (world space), calculate
  * coordinates (in texture space) then store into a new list of projections.
  *
- * @assume The coordinates of the given quad must be contained wholly within
+ * @pre The coordinates of the given quad must be contained wholly within
  * the BSP leaf specified. This is due to an optimization within the lumobj
  * management which separates them according to their position in the BSP.
  *

doomsday/engine/portable/include/r_shadow.h

@@ -58,7 +58,7 @@ float R_ShadowAttenuationFactor(coord_t distance);
  * Project all mobj shadows affecting the given quad (world space), calculate
  * coordinates (in texture space) then store into a new list of projections.
  *
- * @assume The coordinates of the given quad must be contained wholly within
+ * @pre The coordinates of the given quad must be contained wholly within
  * the BSP leaf specified. This is due to an optimization within the mobj
  * management which separates them according to their position in the BSP.
  *

doomsday/engine/portable/include/rend_list.h

@@ -110,7 +110,7 @@ void RL_LoadDefaultRtus(void);
 void RL_MapRtu(uint idx, const rtexmapunit_t* rtu);
 
 /**
- * Copy the configuration for the identified @idx texture unit of
+ * Copy the configuration for the identified @a idx texture unit of
  * the primitive writer's internal state from @a rtu.
  *
  * @param idx  Logical index of the texture unit being configured.
@@ -134,7 +134,7 @@ void RL_Rtu_SetOffsetv(uint idx, float const st[2]);
 void RL_Rtu_TranslateOffset(uint idx, float s, float t);
 void RL_Rtu_TranslateOffsetv(uint idx, float const st[2]);
 
-/// Change the texture assigned to the identified @idx texture unit.
+/// Change the texture assigned to the identified @a idx texture unit.
 void RL_Rtu_SetTextureUnmanaged(uint idx, DGLuint glName);
 
 /**

doomsday/engine/portable/include/sv_pool.h

@@ -411,8 +411,8 @@ uint            Sv_CountUnackedDeltas(uint clientNumber);
  * sound is in itself a 'delta-like' event, there is no need for comparing or
  * to have a register.
  *
- * @important: Assumes no two sounds with the same ID play at the same time
- *             from the same origin at once.
+ * @note Assumes no two sounds with the same ID play at the same time
+ *       from the same origin at once.
  *
  * @param volume  Volume at which to play the sound, or zero for stop-sound.
  * @param clientsMask  -1= all clients.

doomsday/engine/portable/include/sys_direc.h

@@ -85,7 +85,7 @@ void Dir_CleanPathStr(ddstring_t* str);
 char* Dir_CurrentPath(void);
 
 /**
- * Extract just the file name including any extension from @path.
+ * Extract just the file name including any extension from @a path.
  */
 void Dir_FileName(char* name, const char* path, size_t len);
 

doomsday/engine/portable/src/cbuffer.c

@@ -78,7 +78,7 @@ static void lock(CBuffer* cb, boolean yes)
     Sys_Unlock(cb->mutex);
 }
 
-/// \notes Also destroys the data object.
+/// @note Also destroys the data object.
 static void destroyNode(cbnode_t* node)
 {
     assert(node);

doomsday/engine/portable/src/cl_mobj.c

@@ -88,7 +88,7 @@ void checkMobjHash(void)
  */
 static void ClMobj_LinkInHash(mobj_t* mo, thid_t id)
 {
-    /// @fixme Do not assume the CURRENT map.
+    /// @todo Do not assume the CURRENT map.
     cmhash_t* hash = GameMap_ClMobjHash(theMap, id);
     clmoinfo_t* info = ClMobj_GetInfo(mo);
 

doomsday/engine/portable/src/cl_world.c

@@ -314,7 +314,7 @@ void GameMap_DeleteClPolyobj(GameMap* map, clpolyobj_t* mover)
  */
 void Cl_MoverThinker(clplane_t* mover)
 {
-    GameMap* map = theMap; /// @fixme Do not assume mover is from the CURRENT map.
+    GameMap* map = theMap; /// @todo Do not assume mover is from the CURRENT map.
     coord_t original;
     boolean remove = false;
     boolean freeMove;
@@ -516,7 +516,7 @@ void Cl_PolyMoverThinker(clpolyobj_t* mover)
     // Can we get rid of this mover?
     if(!mover->move && !mover->rotate)
     {
-        /// @fixme Do not assume the move is from the CURRENT map.
+        /// @todo Do not assume the move is from the CURRENT map.
         GameMap_DeleteClPolyobj(theMap, mover);
     }
 }
@@ -536,7 +536,7 @@ clpolyobj_t* GameMap_ClPolyobjByPolyobjIndex(GameMap* map, uint index)
 }
 
 /**
- * @important Assumes there is no existing ClPolyobj for Polyobj @a index.
+ * @note Assumes there is no existing ClPolyobj for Polyobj @a index.
  */
 clpolyobj_t* GameMap_NewClPolyobj(GameMap* map, uint polyobjIndex)
 {
@@ -614,7 +614,7 @@ void Cl_ReadSectorDelta2(int deltaType, boolean skip)
     static Plane* dummyPlaneArray[2];
     static Plane dummyPlanes[2];
 
-    GameMap* map = theMap; /// @fixme Do not assume the CURRENT map.
+    GameMap* map = theMap; /// @todo Do not assume the CURRENT map.
     unsigned short num;
     Sector* sec;
     int df;

doomsday/engine/portable/src/dd_main.c

@@ -1149,7 +1149,7 @@ boolean DD_ChangeGame2(Game* game, boolean allowReload)
 
         Sfx_InitLogical();
 
-        /// @fixme Why is this being done here?
+        /// @todo Why is this being done here?
         if(theMap)
         {
             GameMap_InitThinkerLists(theMap, 0x1|0x2);
@@ -1173,7 +1173,7 @@ boolean DD_ChangeGame2(Game* game, boolean allowReload)
         R_InitSvgs();
         R_InitViewWindow();
 
-        /// @fixme Assumes we only cache lumps from non-startup wads.
+        /// @todo Assumes we only cache lumps from non-startup wads.
         Z_FreeTags(PU_CACHE, PU_CACHE);
 
         F_Reset();
@@ -1183,7 +1183,7 @@ boolean DD_ChangeGame2(Game* game, boolean allowReload)
     FI_Shutdown();
     titleFinale = 0; // If the title finale was in progress it isn't now.
 
-    /// @fixme Materials database should not be shutdown during a reload.
+    /// @todo Materials database should not be shutdown during a reload.
     Materials_Shutdown();
 
     VERBOSE(
@@ -2138,7 +2138,7 @@ void* DD_GetVariable(int ddvalue)
         return &valueU;
 
     case DD_TRACE_ADDRESS:
-        /// @fixme Do not cast away const.
+        /// @todo Do not cast away const.
         return (void*)P_TraceLOS();
 
     case DD_TRANSLATIONTABLES_ADDRESS:

doomsday/engine/portable/src/def_main.c

@@ -650,7 +650,7 @@ int Def_GetTextNumForName(const char* name)
 }
 
 /**
- * Escape sequences are un-escaped (\n, \r, \t, \s, \_).
+ * Escape sequences are un-escaped (\\n, \\r, \\t, \\s, \\_).
  */
 void Def_InitTextDef(ddtext_t* txt, char* str)
 {

doomsday/engine/portable/src/edit_map.c

@@ -438,7 +438,7 @@ static void pruneUnusedSectors(editmap_t* map)
 #endif
 
 /**
- * @important Order here is critical!
+ * @warning Order here is critical!
  */
 void MPE_PruneRedundantMapData(editmap_t* map, int flags)
 {
@@ -1251,8 +1251,9 @@ static void hardenPolyobjs(GameMap* dest, editmap_t* src)
 }
 
 /**
- * @algorithm Cast a line horizontally or vertically and see what we hit.
- *           (OUCH, we have to iterate over all linedefs!).
+ * @par Algorithm
+ * Cast a line horizontally or vertically and see what we hit.
+ * (OUCH, we have to iterate over all linedefs!).
  */
 static void testForWindowEffect(editmap_t* map, LineDef* l)
 {
@@ -1401,7 +1402,8 @@ static void countVertexLineOwners(Vertex* vtx, uint* oneSided, uint* twoSided)
 }
 
 /**
- * @algorithm Scan the linedef list looking for possible candidates, checking for
+ * @par Algorithm
+ * Scan the linedef list looking for possible candidates, checking for
  * an odd number of one-sided linedefs connected to a single vertex. This idea
  * courtesy of Graham Jackson.
  */

doomsday/engine/portable/src/finaleinterpreter.c

@@ -413,7 +413,7 @@ static fi_object_t* addObjectToNamespace(fi_namespace_t* names, const char* name
 }
 
 /**
- * \assume There is at most one reference to the object in this scope.
+ * @pre There is at most one reference to the object in this scope.
  */
 static fi_object_t* removeObjectInNamespace(fi_namespace_t* names, fi_object_t* obj)
 {

doomsday/engine/portable/src/fonts.c

@@ -157,15 +157,15 @@ static Uri* composeUriForDirectoryNode(const PathDirectoryNode* node)
     return uri;
 }
 
-/// \assume fontIdMap has been initialized and is large enough!
+/// @pre fontIdMap has been initialized and is large enough!
 static void unlinkDirectoryNodeFromBindIdMap(const PathDirectoryNode* node)
 {
     fontid_t id = findBindIdForDirectoryNode(node);
     if(!validFontId(id)) return; // Not linked.
     fontIdMap[id - 1/*1-based index*/] = NULL;
 }
 
-/// \assume uniqueIdMap has been initialized and is large enough!
+/// @pre uniqueIdMap has been initialized and is large enough!
 static int linkRecordInUniqueIdMap(PathDirectoryNode* node, void* paramaters)
 {
     const fontrecord_t* record = (fontrecord_t*)PathDirectoryNode_UserData(node);
@@ -175,7 +175,7 @@ static int linkRecordInUniqueIdMap(PathDirectoryNode* node, void* paramaters)
     return 0; // Continue iteration.
 }
 
-/// \assume uniqueIdMap is large enough if initialized!
+/// @pre uniqueIdMap is large enough if initialized!
 static int unlinkRecordInUniqueIdMap(PathDirectoryNode* node, void* paramaters)
 {
     const fontrecord_t* record = (fontrecord_t*)PathDirectoryNode_UserData(node);
@@ -262,7 +262,7 @@ static PathDirectoryNode* findDirectoryNodeForPath(PathDirectory* directory, con
     return PathDirectory_Find(directory, PCF_NO_BRANCH|PCF_MATCH_FULL, path, FONTS_PATH_DELIMITER);
 }
 
-/// \assume @a uri has already been validated and is well-formed.
+/// @pre @a uri has already been validated and is well-formed.
 static PathDirectoryNode* findDirectoryNodeForUri(const Uri* uri)
 {
     fontnamespaceid_t namespaceId;