diff --git a/doomsday/engine/portable/include/abstractresource.h b/doomsday/engine/portable/include/abstractresource.h index 4df6dfa840..83c65aa85a 100644 --- a/doomsday/engine/portable/include/abstractresource.h +++ b/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); diff --git a/doomsday/engine/portable/include/audiodriver.h b/doomsday/engine/portable/include/audiodriver.h index 43abdc42d0..67bbc781a9 100644 --- a/doomsday/engine/portable/include/audiodriver.h +++ b/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 diff --git a/doomsday/engine/portable/include/b_command.h b/doomsday/engine/portable/include/b_command.h index 054bc04685..1a798ebe13 100644 --- a/doomsday/engine/portable/include/b_command.h +++ b/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__ diff --git a/doomsday/engine/portable/include/b_util.h b/doomsday/engine/portable/include/b_util.h index cb7ae4b348..88a80bc49b 100644 --- a/doomsday/engine/portable/include/b_util.h +++ b/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__ diff --git a/doomsday/engine/portable/include/binarytree.h b/doomsday/engine/portable/include/binarytree.h index e997aefd85..393ca1ce43 100644 --- a/doomsday/engine/portable/include/binarytree.h +++ b/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); diff --git a/doomsday/engine/portable/include/blockmap.h b/doomsday/engine/portable/include/blockmap.h index 6c05ca6bb0..0eaff776ac 100644 --- a/doomsday/engine/portable/include/blockmap.h +++ b/doomsday/engine/portable/include/blockmap.h @@ -60,7 +60,7 @@ 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); @@ -68,6 +68,7 @@ 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]); diff --git a/doomsday/engine/portable/include/cbuffer.h b/doomsday/engine/portable/include/cbuffer.h index 3e2925ead0..df34a473a0 100644 --- a/doomsday/engine/portable/include/cbuffer.h +++ b/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); diff --git a/doomsday/engine/portable/include/cl_player.h b/doomsday/engine/portable/include/cl_player.h index 799cea8656..5e3fc18747 100644 --- a/doomsday/engine/portable/include/cl_player.h +++ b/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); diff --git a/doomsday/engine/portable/include/colorpalette.h b/doomsday/engine/portable/include/colorpalette.h index 15c1780531..ab382c67de 100644 --- a/doomsday/engine/portable/include/colorpalette.h +++ b/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]. + *
 [0,1,2] == RGB
+ * [2,1,0] == BGR
+ * @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 + *
 [0,1,2] == RGB
+ * [2,1,0] == BGR
* @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. */ diff --git a/doomsday/engine/portable/include/con_main.h b/doomsday/engine/portable/include/con_main.h index 619b227894..eddc565d43 100644 --- a/doomsday/engine/portable/include/con_main.h +++ b/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 */ diff --git a/doomsday/engine/portable/include/dd_games.h b/doomsday/engine/portable/include/dd_games.h index 5b8b6f2c72..035a2f7e3f 100644 --- a/doomsday/engine/portable/include/dd_games.h +++ b/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); diff --git a/doomsday/engine/portable/include/map/bsp/superblockmap.h b/doomsday/engine/portable/include/map/bsp/superblockmap.h index 0231110035..dc1c4438f2 100644 --- a/doomsday/engine/portable/include/map/bsp/superblockmap.h +++ b/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: /** diff --git a/doomsday/engine/portable/include/pathdirectory.h b/doomsday/engine/portable/include/pathdirectory.h index 69f185d45b..067ca415c1 100644 --- a/doomsday/engine/portable/include/pathdirectory.h +++ b/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: diff --git a/doomsday/engine/portable/src/b_command.c b/doomsday/engine/portable/src/b_command.c index 188b9973f1..c7d6591f67 100644 --- a/doomsday/engine/portable/src/b_command.c +++ b/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; diff --git a/doomsday/engine/portable/src/b_util.c b/doomsday/engine/portable/src/b_util.c index 7316809d5f..c379dd863c 100644 --- a/doomsday/engine/portable/src/b_util.c +++ b/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) diff --git a/doomsday/engine/portable/src/map/entitydatabase.cpp b/doomsday/engine/portable/src/map/entitydatabase.cpp index d78b712d56..4f9c613197 100644 --- a/doomsday/engine/portable/src/map/entitydatabase.cpp +++ b/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 © 2007-2012 Daniel Swanson diff --git a/doomsday/engine/portable/src/resource/texture.cpp b/doomsday/engine/portable/src/resource/texture.cpp index 25e72c0ff0..935cd4988b 100644 --- a/doomsday/engine/portable/src/resource/texture.cpp +++ b/doomsday/engine/portable/src/resource/texture.cpp @@ -1,5 +1,5 @@ /** - * @file texture.c + * @file texture.cpp * Logical texture. @ingroup resource * * @authors Copyright © 2003-2012 Jaakko Keränen diff --git a/doomsday/engine/portable/src/resource/texturevariant.cpp b/doomsday/engine/portable/src/resource/texturevariant.cpp index 4ea6b3034b..89df592303 100644 --- a/doomsday/engine/portable/src/resource/texturevariant.cpp +++ b/doomsday/engine/portable/src/resource/texturevariant.cpp @@ -1,5 +1,5 @@ /** - * @file texturevariant.c + * @file texturevariant.cpp * Logical texture variant. @ingroup resource * * @authors Copyright © 2012 Daniel Swanson