From afb8643158ff88126be04e3fc0bbe4270c766503 Mon Sep 17 00:00:00 2001 From: danij Date: Fri, 9 Nov 2012 04:31:02 +0000 Subject: [PATCH] Documentation: Various Doxygen apidoc fixes --- doomsday/engine/portable/include/dam_main.h | 4 +- doomsday/engine/portable/include/dd_main.h | 2 +- doomsday/engine/portable/include/file.h | 5 +- doomsday/engine/portable/include/fonts.h | 87 +++++++++---------- doomsday/engine/portable/include/fs_util.h | 12 +-- doomsday/engine/portable/include/game.h | 1 + .../portable/include/resourcenamespace.h | 2 +- doomsday/engine/portable/src/dam_main.cpp | 5 +- doomsday/engine/portable/src/edit_map.cpp | 11 +-- doomsday/engine/portable/src/fs_main.cpp | 1 + doomsday/engine/portable/src/lumpindex.cpp | 2 + .../engine/portable/src/resource/models.cpp | 9 +- .../engine/portable/src/resourcenamespace.cpp | 23 ++--- .../engine/portable/src/sys_reslocator.cpp | 10 +-- 14 files changed, 87 insertions(+), 87 deletions(-) diff --git a/doomsday/engine/portable/include/dam_main.h b/doomsday/engine/portable/include/dam_main.h index 481ee4cfd2..aaeb8b3bd7 100644 --- a/doomsday/engine/portable/include/dam_main.h +++ b/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 © 2007-2012 Daniel Swanson + * @author Copyright © 2007-2012 Daniel Swanson * * @par License * GPL: http://www.gnu.org/licenses/gpl.html diff --git a/doomsday/engine/portable/include/dd_main.h b/doomsday/engine/portable/include/dd_main.h index 0161141ffd..d88c8bbedf 100644 --- a/doomsday/engine/portable/include/dd_main.h +++ b/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); diff --git a/doomsday/engine/portable/include/file.h b/doomsday/engine/portable/include/file.h index 2aca0fa429..90ce792fef 100644 --- a/doomsday/engine/portable/include/file.h +++ b/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. diff --git a/doomsday/engine/portable/include/fonts.h b/doomsday/engine/portable/include/fonts.h index 8d2d36273e..a47693df8c 100644 --- a/doomsday/engine/portable/include/fonts.h +++ b/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 - *\author Copyright © 2005-2012 Daniel Swanson - * - * 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 © 2003-2012 Jaakko Keränen + * @author Copyright © 2005-2012 Daniel Swanson + * + * @par License + * GPL: http://www.gnu.org/licenses/gpl.html + * + * 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 */ -#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 */ diff --git a/doomsday/engine/portable/include/fs_util.h b/doomsday/engine/portable/include/fs_util.h index ce6f84083b..9be9600f42 100644 --- a/doomsday/engine/portable/include/fs_util.h +++ b/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. * diff --git a/doomsday/engine/portable/include/game.h b/doomsday/engine/portable/include/game.h index 8791f0a2ab..7f2782a5c9 100644 --- a/doomsday/engine/portable/include/game.h +++ b/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); diff --git a/doomsday/engine/portable/include/resourcenamespace.h b/doomsday/engine/portable/include/resourcenamespace.h index 4fe952c992..2579c7cce3 100644 --- a/doomsday/engine/portable/include/resourcenamespace.h +++ b/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. diff --git a/doomsday/engine/portable/src/dam_main.cpp b/doomsday/engine/portable/src/dam_main.cpp index 5703902714..7ce4135312 100644 --- a/doomsday/engine/portable/src/dam_main.cpp +++ b/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 © 2007-2012 Daniel Swanson + * @author Copyright © 2007-2012 Daniel Swanson * * @par License * GPL: http://www.gnu.org/licenses/gpl.html diff --git a/doomsday/engine/portable/src/edit_map.cpp b/doomsday/engine/portable/src/edit_map.cpp index 7f16681abc..595a10964c 100644 --- a/doomsday/engine/portable/src/edit_map.cpp +++ b/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 © 2007-2012 Daniel Swanson - * @authors Copyright © 2000-2007 Andrew Apted - * @authors Copyright © 1998-2000 Colin Reed - * @authors Copyright © 1998-2000 Lee Killough + * @author Copyright © 2007-2012 Daniel Swanson + * @author Copyright © 2000-2007 Andrew Apted + * @author Copyright © 1998-2000 Colin Reed + * @author Copyright © 1998-2000 Lee Killough * * @par License * GPL: http://www.gnu.org/licenses/gpl.html diff --git a/doomsday/engine/portable/src/fs_main.cpp b/doomsday/engine/portable/src/fs_main.cpp index cfec6e7999..b2cfa7ccba 100644 --- a/doomsday/engine/portable/src/fs_main.cpp +++ b/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. diff --git a/doomsday/engine/portable/src/lumpindex.cpp b/doomsday/engine/portable/src/lumpindex.cpp index 0c9c1d8a48..a5cfba2508 100644 --- a/doomsday/engine/portable/src/lumpindex.cpp +++ b/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) diff --git a/doomsday/engine/portable/src/resource/models.cpp b/doomsday/engine/portable/src/resource/models.cpp index c5e5d35af7..8651f4dbc2 100644 --- a/doomsday/engine/portable/src/resource/models.cpp +++ b/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 - * @authors Copyright © 2006-2012 Daniel Swanson - * @authors Copyright © 2006 Jamie Jones + * @author Copyright © 2003-2012 Jaakko Keränen + * @author Copyright © 2006-2012 Daniel Swanson + * @author Copyright © 2006 Jamie Jones * * @par License * GPL: http://www.gnu.org/licenses/gpl.html diff --git a/doomsday/engine/portable/src/resourcenamespace.cpp b/doomsday/engine/portable/src/resourcenamespace.cpp index aa1009a6eb..e833b40b47 100644 --- a/doomsday/engine/portable/src/resourcenamespace.cpp +++ b/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,7 +468,7 @@ 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; @@ -475,7 +476,7 @@ bool ResourceNamespace::addSearchPath(PathGroup group, de::Uri const& uri, int f } // 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; diff --git a/doomsday/engine/portable/src/sys_reslocator.cpp b/doomsday/engine/portable/src/sys_reslocator.cpp index ce19440e24..689ba2a5b1 100644 --- a/doomsday/engine/portable/src/sys_reslocator.cpp +++ b/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) {