Documentation: Various Doxygen apidoc fixes

doomsday/engine/portable/include/dam_main.h

@@ -1,8 +1,8 @@
 /**
- * @file dam_main.c
+ * @file dam_main.h
  * Doomsday Archived Map (DAM), map management. @ingroup map
  *
- * @authors Copyright &copy; 2007-2012 Daniel Swanson <danij@dengine.net>
+ * @author Copyright &copy; 2007-2012 Daniel Swanson <danij@dengine.net>
  *
  * @par License
  * GPL: http://www.gnu.org/licenses/gpl.html

doomsday/engine/portable/include/dd_main.h

@@ -161,7 +161,7 @@ void DD_DestroyGames(void);
 
 boolean DD_GameInfo(struct gameinfo_s* info);
 
-void DD_AddGameResource(gameid_t gameId, resourceclass_t rclass, int rflags, char const* _names, void* params);
+void DD_AddGameResource(gameid_t game, resourceclass_t rclass, int rflags, char const* names, void* params);
 
 gameid_t DD_DefineGame(struct gamedef_s const* def);
 

doomsday/engine/portable/include/file.h

@@ -193,7 +193,10 @@ class File1
      * the file and therefore *this* is that lump. Subclasses with multiple lumps
      * should override this function accordingly.
      */
-    virtual File1& lump(int /*lumpIdx*/) { return *this; }
+    virtual File1& lump(int lumpIdx) {
+        DENG_UNUSED(lumpIdx);
+        return *this;
+    }
 
     /**
      * Read the file data into @a buffer.

doomsday/engine/portable/include/fonts.h

@@ -1,54 +1,47 @@
-/**\file fonts.h
- *\section License
- * License: GPL
- * Online License Link: http://www.gnu.org/licenses/gpl.html
- *
- *\author Copyright © 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
- *\author Copyright © 2005-2012 Daniel Swanson <danij@dengine.net>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin St, Fifth Floor,
- * Boston, MA  02110-1301  USA
- */
-
 /**
- * Fonts Collection.
- * @ingroup refresh
+ * @file fonts.h
+ *
+ * Font Resources. @ingroup resource
  *
- * 'Runtime' fonts are not loaded until precached or actually needed.
- * They may be cleared, in which case they will be reloaded when needed.
+ * 'Runtime' fonts are not loaded until precached or actually needed. They may
+ * be cleared, in which case they will be reloaded when needed.
  *
- * 'System' fonts are loaded at startup and remain in memory all the time.
- * After clearing they must be manually reloaded.
+ * 'System' fonts are loaded at startup and remain in memory all the time. After
+ * clearing they must be manually reloaded.
  *
- * 'Clear'ing a Font is to "undefine" it - any names bound to it are
- * deleted, any GL textures acquired for it are 'released'. The Font
- * instance record used to represent it is also deleted.
+ * 'Clear'ing a Font is to "undefine" it - any names bound to it are deleted,
+ * any GL textures acquired for it are 'released'. The Font instance record used
+ * to represent it is also deleted.
  *
- * 'Release'ing a Font will leave it defined (any names bound to it
- * will persist) and any GL textures acquired for it are so too released.
- * Note that the Font instance record used to represent it will NOT
- * be deleted.
+ * 'Release'ing a Font will leave it defined (any names bound to it will persist)
+ * and any GL textures acquired for it are so too released. Note that the Font
+ * instance record used to represent it will NOT be deleted.
  *
  * Thus there are two general states for fonts in the collection:
  *
  *   1) Declared but not defined.
  *   2) Declared and defined.
+ *
+ * @author Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @author Copyright &copy; 2005-2012 Daniel Swanson <danij@dengine.net>
+ *
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
+ *
+ * <small>This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by the
+ * Free Software Foundation; either version 2 of the License, or (at your
+ * option) any later version. This program is distributed in the hope that it
+ * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+ * Public License for more details. You should have received a copy of the GNU
+ * General Public License along with this program; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
  */
 
-#ifndef LIBDENG_REFRESH_FONTS_H
-#define LIBDENG_REFRESH_FONTS_H
+#ifndef LIBDENG_RESOURCE_FONTS_H
+#define LIBDENG_RESOURCE_FONTS_H
 
 #include "uri.h"
 #include "def_data.h"
@@ -158,13 +151,15 @@ void Fonts_RebuildFromFile(struct font_s* font, const char* resourcePath);
  *
  * @return  Unique identifier of the found texture else @c NOFONTID.
  */
-fontid_t Fonts_ResolveUri(const Uri* uri); /*quiet=!(verbose >= 1)*/
+fontid_t Fonts_ResolveUri(Uri const * uri); /*quiet=!(verbose >= 1)*/
 
 /**
  * @copydoc Fonts_ResolveUri()
- * @param quiet  Suppresses the console message that is printed if the Uri cannot be found.
+ *
+ * @param uri       Either a path or URN to the font.
+ * @param quiet     @c true = suppress the console message that is printed if the Uri cannot be found.
  */
-fontid_t Fonts_ResolveUri2(const Uri* uri, boolean quiet);
+fontid_t Fonts_ResolveUri2(Uri const* uri, boolean quiet);
 
 /// Same as Fonts::ResolveUri except @a uri is a C-string.
 fontid_t Fonts_ResolveUriCString2(const char* uri, boolean quiet);
@@ -217,7 +212,7 @@ int Fonts_Iterate(fontnamespaceid_t namespaceId, int (*callback)(struct font_s*
 int Fonts_IterateDeclared2(fontnamespaceid_t namespaceId, int (*callback)(fontid_t textureId, void* paramaters), void* paramaters);
 int Fonts_IterateDeclared(fontnamespaceid_t namespaceId, int (*callback)(fontid_t textureId, void* paramaters)); /*paramaters=NULL*/
 
-/**
+/*
  * Here follows miscellaneous routines currently awaiting refactoring into the
  * revised resource and texture management APIs.
  */
@@ -227,8 +222,8 @@ int Fonts_IterateDeclared(fontnamespaceid_t namespaceId, int (*callback)(fontid_
  * acquired from the GL subsystem (v-buffers, d-lists, textures, etc...)
  * for fonts.
  *
- * \note Called automatically prior to module shutdown.
- * \todo Define new texture namespaces for font textures and refactor away.
+ * @note Called automatically prior to module shutdown.
+ * @todo Define new texture namespaces for font textures and refactor away.
  */
 void Fonts_ReleaseRuntimeTextures(void);
 void Fonts_ReleaseSystemTextures(void);
@@ -251,4 +246,4 @@ int Fonts_CharWidth(struct font_s* font, unsigned char ch);
 } // extern "C"
 #endif
 
-#endif /* LIBDENG_REFRESH_FONTS_H */
+#endif /* LIBDENG_RESOURCE_FONTS_H */

doomsday/engine/portable/include/fs_util.h

@@ -182,16 +182,18 @@ int F_MatchFileName(const char* filePath, const char* pattern);
  * Write the data associated with the specified lump index to @a fileName.
  *
  * @param lumpNum           Absolute index of the lump to open.
- * @param fileName          If not @c NULL write the associated data to this path.
- *                          Can be @c NULL in which case the fileName will be chosen automatically.
  *
  * @return  @c true iff successful.
  */
-boolean F_DumpLump2(lumpnum_t lumpNum, char const* fileName);
-
-/// @copydoc F_DumpLump2
 boolean F_DumpLump(lumpnum_t lumpNum/*, fileName = 0*/);
 
+/**
+ * @copydoc F_DumpLump
+ * @param fileName          If not @c NULL write the associated data to this path.
+ *                          Can be @c NULL in which case the fileName will be chosen automatically.
+ */
+boolean F_DumpLump2(lumpnum_t lumpNum, char const* fileName);
+
 /**
  * Write data into a file.
  *

doomsday/engine/portable/include/game.h

@@ -116,6 +116,7 @@ class Game
      *       type are loaded.
      *
      * @param rclass  Class of resource being added.
+     * @param record  ResourceRecord to add.
      */
     Game& addResource(resourceclass_t rclass, ResourceRecord& record);
 

doomsday/engine/portable/include/resourcenamespace.h

@@ -144,7 +144,7 @@ namespace de
         /**
          * Finds all resources in this namespace.
          *
-         * @param searchpath    If not @c NULL, only consider resources whose
+         * @param searchPath    If not @c NULL, only consider resources whose
          *                      name matches that which will be extracted from
          *                      this path.
          * @param found         Set of resources that match the result.

doomsday/engine/portable/src/dam_main.cpp

@@ -1,8 +1,9 @@
 /**
- * @file dam_main.c
+ * @file dam_main.cpp
+ *
  * Doomsday Archived Map (DAM), map management. @ingroup map
  *
- * @authors Copyright &copy; 2007-2012 Daniel Swanson <danij@dengine.net>
+ * @author Copyright &copy; 2007-2012 Daniel Swanson <danij@dengine.net>
  *
  * @par License
  * GPL: http://www.gnu.org/licenses/gpl.html

doomsday/engine/portable/src/edit_map.cpp

@@ -1,11 +1,12 @@
 /**
- * @file edit_map.c
+ * @file edit_map.cpp
+
  * Map Editor interface. @ingroup map
  *
- * @authors Copyright &copy; 2007-2012 Daniel Swanson <danij@dengine.net>
- * @authors Copyright &copy; 2000-2007 Andrew Apted <ajapted@gmail.com>
- * @authors Copyright &copy; 1998-2000 Colin Reed <cph@moria.org.uk>
- * @authors Copyright &copy; 1998-2000 Lee Killough <killough@rsn.hp.com>
+ * @author Copyright &copy; 2007-2012 Daniel Swanson <danij@dengine.net>
+ * @author Copyright &copy; 2000-2007 Andrew Apted <ajapted@gmail.com>
+ * @author Copyright &copy; 1998-2000 Colin Reed <cph@moria.org.uk>
+ * @author Copyright &copy; 1998-2000 Lee Killough <killough@rsn.hp.com>
  *
  * @par License
  * GPL: http://www.gnu.org/licenses/gpl.html

doomsday/engine/portable/src/fs_main.cpp

@@ -1671,6 +1671,7 @@ AutoStr* F_ComposeLumpPath(struct file1_s* file, int lumpIdx)
 #define DEFAULT_PATHTOSTRINGFLAGS       (PTSF_QUOTED)
 
 /**
+ * @param files      List of files from which to compose the path string.
  * @param flags      @ref pathToStringFlags
  * @param delimiter  If not @c NULL, path fragments in the resultant string
  *                   will be delimited by this.

doomsday/engine/portable/src/lumpindex.cpp

@@ -109,6 +109,8 @@ struct LumpIndex::Instance
 
     /**
      * @param pruneFlags  Passed by reference to avoid deep copy on value-write.
+     * @param file        Flag only those lumps contained by this file.
+     *
      * @return Number of lumps newly flagged during this op.
      */
     int flagContainedLumps(QBitArray& pruneFlags, File1& file)

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

@@ -1,12 +1,13 @@
 /**
- * @file r_model.c
+ * @file models.cpp
+ *
  * 3D Model Resources. @ingroup resource
  *
  * MD2/DMD2 loading and setup.
  *
- * @authors Copyright © 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
- * @authors Copyright © 2006-2012 Daniel Swanson <danij@dengine.net>
- * @authors Copyright © 2006 Jamie Jones <jamie_jones_au@yahoo.com.au>
+ * @author Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @author Copyright &copy; 2006-2012 Daniel Swanson <danij@dengine.net>
+ * @author Copyright &copy; 2006 Jamie Jones <jamie_jones_au@yahoo.com.au>
  *
  * @par License
  * GPL: http://www.gnu.org/licenses/gpl.html

doomsday/engine/portable/src/resourcenamespace.cpp

@@ -310,11 +310,12 @@ struct ResourceNamespace::Instance
     }
 
     /**
-     * @param filePath  Possibly-relative path to an element in the virtual file system.
-     * @param isFolder  @c true if @a filePath is a folder in the virtual file system.
-     * @param nodeType  Type of element, either a branch (directory) or a leaf (file).
+     * @param descendBranch     @c true = descend this branch (if it is a branch).
+     * @param filePath          Possibly-relative path to an element in the virtual file system.
+     * param isFolder           @c true = @a filePath is a folder in the virtual file system.
+     * @param flags             @ref searchPathFlags
      */
-    void addDirectoryPathNodesAndMaybeDescendBranch(bool descendBranches,
+    void addDirectoryPathNodesAndMaybeDescendBranch(bool descendBranch,
         ddstring_t const* filePath, bool /*isFolder*/, int flags)
     {
         // Add this path to the directory.
@@ -324,7 +325,7 @@ struct ResourceNamespace::Instance
             if(!node->isLeaf())
             {
                 // Descend into this subdirectory?
-                if(descendBranches)
+                if(descendBranch)
                 {
                     // Already processed?
                     if(node->userValue())
@@ -453,12 +454,12 @@ bool ResourceNamespace::add(PathTree::Node& resourceNode)
     return isNewNode;
 }
 
-bool ResourceNamespace::addSearchPath(PathGroup group, de::Uri const& uri, int flags)
+bool ResourceNamespace::addSearchPath(PathGroup group, de::Uri const& path, int flags)
 {
     // Ensure this is a well formed path.
-    if(Str_IsEmpty(uri.path()) ||
-       !Str_CompareIgnoreCase(uri.path(), "/") ||
-       Str_RAt(uri.path(), 0) != '/')
+    if(Str_IsEmpty(path.path()) ||
+       !Str_CompareIgnoreCase(path.path(), "/") ||
+       Str_RAt(path.path(), 0) != '/')
         return false;
 
     // The addition of a new search path means the namespace is now dirty.
@@ -467,15 +468,15 @@ bool ResourceNamespace::addSearchPath(PathGroup group, de::Uri const& uri, int f
     // Have we seen this path already (we don't want duplicates)?
     DENG2_FOR_EACH(SearchPaths, i, d->searchPaths)
     {
-        if(i->uri() == uri)
+        if(i->uri() == path)
         {
             i->setFlags(flags);
             return true;
         }
     }
 
     // Prepend to the path list - newer paths have priority.
-    de::Uri* uriCopy = new de::Uri(uri);
+    de::Uri* uriCopy = new de::Uri(path);
     d->searchPaths.insert(group, SearchPath(flags, *uriCopy));
 
     return true;

doomsday/engine/portable/src/sys_reslocator.cpp

@@ -124,6 +124,7 @@ static uint numNamespaces = 0;
 /**
  * @param name      Unique symbolic name of this namespace. Must be at least
  *                  @c RESOURCENAMESPACE_MINNAMELENGTH characters long.
+ * @param flags     @ref resourceNamespaceFlags
  */
 ResourceNamespace* F_CreateResourceNamespace(char const* name, byte flags);
 
@@ -255,9 +256,6 @@ static bool tryFindResource2(resourceclass_t rclass, ddstring_t const* rawSearch
     return false;
 }
 
-/**
- * @param flags  @see resourceLocationFlags
- */
 static bool tryFindResource(int flags, resourceclass_t rclass, ddstring_t const* searchPath,
     ddstring_t* foundPath, ResourceNamespaceInfo* rnamespaceInfo)
 {
@@ -316,9 +314,6 @@ static bool tryFindResource(int flags, resourceclass_t rclass, ddstring_t const*
     return found;
 }
 
-/**
- * @param flags  @see resourceLocationFlags
- */
 static bool findResource2(resourceclass_t rclass, ddstring_t const* searchPath,
     ddstring_t* foundPath, int flags, ddstring_t const* optionalSuffix,
     ResourceNamespaceInfo* rnamespaceInfo)
@@ -364,9 +359,6 @@ static bool findResource2(resourceclass_t rclass, ddstring_t const* searchPath,
     return found;
 }
 
-/**
- * @param flags  @see resourceLocationFlags
- */
 static int findResource(resourceclass_t rclass, uri_s const* const* list,
     ddstring_t* foundPath, int flags, ddstring_t const* optionalSuffix)
 {