From 0d4be585dc8f570f69c7b01730de1e3b325c3119 Mon Sep 17 00:00:00 2001 From: skyjake Date: Fri, 13 Jan 2012 12:18:40 +0200 Subject: [PATCH] Documentation: Improving the public API docs --- doomsday/engine/api/dd_api.h | 74 ++++++++++++------------- doomsday/engine/api/dd_share.h | 99 ++++++++++++++++++++++++---------- doomsday/engine/api/doomsday.h | 4 +- 3 files changed, 111 insertions(+), 66 deletions(-) diff --git a/doomsday/engine/api/dd_api.h b/doomsday/engine/api/dd_api.h index 0502a7649d..23b5a89473 100644 --- a/doomsday/engine/api/dd_api.h +++ b/doomsday/engine/api/dd_api.h @@ -1,10 +1,9 @@ -/**\file dd_api.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html +/** + * @file dd_api.h + * Data structures for the engine/plugin interfaces. * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2006-2012 Daniel Swanson + * @section 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 @@ -20,10 +19,9 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, * Boston, MA 02110-1301 USA - */ - -/** - * Data Structures for the Engine/Plugin Interfaces. + * + * @author Copyright © 2003-2012 Jaakko Keränen + * @author Copyright © 2006-2012 Daniel Swanson */ #ifndef LIBDENG_API_H @@ -32,12 +30,12 @@ #include "dd_share.h" /** - * The data exported out of the Doomsday engine. - * \todo Refactor away - there should be no need for an ABI in this direction. + * The data exported out of the Doomsday engine. @ingroup game + * @todo Refactor away - there should be no need for an ABI in this direction. */ typedef struct game_import_s { - size_t apiSize; // sizeof(game_import_t) - int version; // Doomsday Engine version. + size_t apiSize; ///< sizeof(game_import_t) + int version; ///< Doomsday Engine version. // // DATA @@ -53,10 +51,10 @@ typedef struct game_import_s { } game_import_t; /** - * The routines/data exported from the game DLL. + * The routines/data exported from the game plugin. @ingroup game */ typedef struct { - size_t apiSize; // sizeof(game_export_t) + size_t apiSize; ///< sizeof(game_export_t) // Base-level. void (*PreInit) (gameid_t gameId); @@ -96,7 +94,7 @@ typedef struct { * dimensions prior to calling this. * * Example subdivision of the game window into four view ports: - * + * 
      *     (0,0)-----------------------. X
      *       | .--------. |            |
      *       | | window | |            |
@@ -109,6 +107,7 @@ typedef struct {
      *       |    port #2 |    port #3 |
      *       '--------------------(xn-1, yn-1)
      *       Y               Game Window
+     *
* * @param port Logical number of this view port. * @param portGeometry Geometry of the view port in real screen pixels. @@ -117,11 +116,9 @@ typedef struct { * * @param player Console player number associated with the view port. * @param layer Logical layer identifier for the content to be drawn: - * - * 0: The bottom-most layer and the one which generally contains the + * - 0: The bottom-most layer and the one which generally contains the * call to R_RenderPlayerView. - * - * 1: Displays to be drawn on top of view window (after bordering), + * - 1: Displays to be drawn on top of view window (after bordering), * such as the player HUD. */ void (*DrawViewPort) (int port, const RectRaw* portGeometry, @@ -147,29 +144,34 @@ typedef struct { size_t polyobjSize; // sizeof(polyobj_t) // Map data setup - // This routine is called before any data is read - // (with the number of items to be read) to allow the - // game do any initialization it needs (eg create an - // array of its own private data structures). + /** + * Called before any data is read (with the number of items to be read) to + * allow the game do any initialization it needs (eg create an array of its + * own private data structures). + */ void (*SetupForMapData) (int type, uint num); - // This routine is called when trying to assign a value read - // from the map data (to a property known to us) that we don't - // know what to do with. - - // (eg the side->toptexture field contains a text string that - // we don't understand but the game might). - - // The action code returned by the game depends on the context. + /** + * Called when trying to assign a value read from the map data (to a + * property known to us) that we don't know what to do with. + * + * (eg the side->toptexture field contains a text string that + * we don't understand but the game might). + * + * @return The action code returned by the game depends on the context. + */ int (*HandleMapDataPropertyValue) (uint id, int dtype, int prop, valuetype_t type, void* data); // Post map setup - // The engine calls this to inform the game of any changes it is - // making to map data object to which the game might want to - // take further action. + /** + * The engine calls this to inform the game of any changes it is + * making to map data object to which the game might want to + * take further action. + */ int (*HandleMapObjectStatusReport) (int code, uint id, int dtype, void* data); } game_export_t; +/// Function pointer for @c GetGameAPI() (exported by game plugin). @ingroup game typedef game_export_t* (*GETGAMEAPI) (game_import_t *); #endif /* LIBDENG_API_H */ diff --git a/doomsday/engine/api/dd_share.h b/doomsday/engine/api/dd_share.h index 5632e637ab..f86ed7aaf8 100644 --- a/doomsday/engine/api/dd_share.h +++ b/doomsday/engine/api/dd_share.h @@ -72,6 +72,8 @@ extern "C" { // //------------------------------------------------------------------------ +/// @defgroup apiFlags Flags + /// Maximum number of players supported by the engine. #define DDMAXPLAYERS 16 @@ -338,10 +340,14 @@ enum { // //------------------------------------------------------------------------ +/** + * @defgroup game Game + */ + /** * Defines the numerous high-level properties of a logical game component. * Note that this is POD; no construction or destruction is needed. - * @see DD_DefineGame() + * @see DD_DefineGame() @ingroup game */ typedef struct gamedef_s { /** @@ -370,7 +376,7 @@ typedef struct gamedef_s { /** * Extended info about a registered game component. - * @see DD_GameInfo() + * @see DD_GameInfo() @ingroup game */ typedef struct gameinfo_s { const char* title; @@ -378,11 +384,9 @@ typedef struct gameinfo_s { const char* identityKey; } GameInfo; -/// @defgroup apiFlags Flags - /** * @defgroup resourceFlags Resource Flags - * @ingroup apiFlags + * @ingroup apiFlags resource */ ///@{ #define RF_STARTUP 0x1 ///< A required resource needed for and loaded during game start up (can't be a virtual file). @@ -394,6 +398,10 @@ typedef struct gameinfo_s { // //------------------------------------------------------------------------ +/** + * @defgroup math Math Routines + */ +///@{ #define FRACBITS 16 #define FRACUNIT (1<= FONTNAMESPACE_FIRST && (val) <= FONTNAMESPACE_LAST) /// Patch Info @@ -1329,6 +1348,24 @@ typedef unsigned int colorpaletteid_t; /// @defgroup console Console +/** + * @defgroup bindings Bindings + * @ingroup input + * Event and controller bindings. + * Input events and input controller state can be bound to console commands + * and player controls. + */ + +/** + * @defgroup cvar Console Variables + * @ingroup console + */ + +/** + * @defgroup ccmd Console Commands + * @ingroup console + */ + /** * @defgroup busyModeFlags Busy Mode Flags * @ingroup console apiFlags @@ -1362,7 +1399,7 @@ typedef unsigned int colorpaletteid_t; #define CPF_TRANSMIT 0x80000000 ///< If server, sent to all clients. ///@} -/// Argument type for B_BindingsForControl(). +/// Argument type for B_BindingsForControl(). @ingroup bindings typedef enum bfcinverse_e { BFCI_BOTH, BFCI_ONLY_NON_INVERSE, @@ -1371,7 +1408,7 @@ typedef enum bfcinverse_e { /** * @defgroup consoleCommandFlags Console Command Flags - * @ingroup console apiFlags + * @ingroup ccmd apiFlags */ ///@{ #define CMDF_NO_NULLGAME 0x00000001 ///< Not available unless a game is loaded. @@ -1380,7 +1417,7 @@ typedef enum bfcinverse_e { /** * @defgroup consoleUsageFlags Console Command Usage Flags - * @ingroup console apiFlags + * @ingroup ccmd apiFlags * The method(s) that @em CANNOT be used to invoke a console command, used with * @ref commandSource. */ @@ -1398,7 +1435,7 @@ typedef enum bfcinverse_e { /** * @defgroup commandSource Command Sources - * @ingroup console + * @ingroup ccmd * Where a console command originated. */ ///@{ @@ -1415,7 +1452,7 @@ typedef enum bfcinverse_e { /** * Console command template. Used with Con_AddCommand(). - * @ingroup console + * @ingroup ccmd */ typedef struct ccmdtemplate_s { /// Name of the command. @@ -1435,18 +1472,22 @@ typedef struct ccmdtemplate_s { #define D_CMD(x) int CCmd##x(byte src, int argc, char** argv) /** - * Helper macros for registering new console commands. - * @ingroup console + * Helper macro for registering new console commands. + * @ingroup ccmd */ #define C_CMD(name, argTemplate, fn) \ { ccmdtemplate_t _template = { name, argTemplate, CCmd##fn, 0 }; Con_AddCommand(&_template); } +/** + * Helper macro for registering new console commands. + * @ingroup ccmd + */ #define C_CMD_FLAGS(name, argTemplate, fn, flags) \ { ccmdtemplate_t _template = { name, argTemplate, CCmd##fn, flags }; Con_AddCommand(&_template); } /** * @defgroup consoleVariableFlags Console Variable Flags - * @ingroup apiFlags console + * @ingroup apiFlags cvar */ ///@{ #define CVF_NO_ARCHIVE 0x1 ///< Not written in/read from the defaults file. @@ -1460,7 +1501,7 @@ typedef struct ccmdtemplate_s { /** * @defgroup setVariableFlags Console Set Variable Flags - * @ingroup apiFlags console + * @ingroup apiFlags cvar * Use with the various Con_Set* routines (e.g., Con_SetInteger2()). */ ///@{ @@ -1482,7 +1523,7 @@ typedef enum { /** * Console variable template. Used with Con_AddVariable(). - * @ingroup console + * @ingroup cvar */ typedef struct cvartemplate_s { /// Path of the variable. @@ -1508,48 +1549,48 @@ typedef struct cvartemplate_s { { cvartemplate_t _template = { path, flags, type, ptr, min, max, notifyChanged }; \ Con_AddVariable(&_template); } -/// Helper macro for registering a new byte console variable. @ingroup console +/// Helper macro for registering a new byte console variable. @ingroup cvar #define C_VAR_BYTE(path, ptr, flags, min, max) \ C_VAR(path, ptr, CVT_BYTE, flags, min, max, NULL) -/// Helper macro for registering a new integer console variable. @ingroup console +/// Helper macro for registering a new integer console variable. @ingroup cvar #define C_VAR_INT(path, ptr, flags, min, max) \ C_VAR(path, ptr, CVT_INT, flags, min, max, NULL) -/// Helper macro for registering a new float console variable. @ingroup console +/// Helper macro for registering a new float console variable. @ingroup cvar #define C_VAR_FLOAT(path, ptr, flags, min, max) \ C_VAR(path, ptr, CVT_FLOAT, flags, min, max, NULL) -/// Helper macro for registering a new text console variable. @ingroup console +/// Helper macro for registering a new text console variable. @ingroup cvar #define C_VAR_CHARPTR(path, ptr, flags, min, max) \ C_VAR(path, ptr, CVT_CHARPTR, flags, min, max, NULL) -/// Helper macro for registering a new Uri console variable. @ingroup console +/// Helper macro for registering a new Uri console variable. @ingroup cvar #define C_VAR_URIPTR(path, ptr, flags, min, max) \ C_VAR(path, ptr, CVT_URIPTR, flags, min, max, NULL) /// Same as C_VAR_BYTE() except allows specifying a callback function for -/// change notification. @ingroup console +/// change notification. @ingroup cvar #define C_VAR_BYTE2(path, ptr, flags, min, max, notifyChanged) \ C_VAR(path, ptr, CVT_BYTE, flags, min, max, notifyChanged) /// Same as C_VAR_INT() except allows specifying a callback function for -/// change notification. @ingroup console +/// change notification. @ingroup cvar #define C_VAR_INT2(path, ptr, flags, min, max, notifyChanged) \ C_VAR(path, ptr, CVT_INT, flags, min, max, notifyChanged) /// Same as C_VAR_FLOAT() except allows specifying a callback function for -/// change notification. @ingroup console +/// change notification. @ingroup cvar #define C_VAR_FLOAT2(path, ptr, flags, min, max, notifyChanged) \ C_VAR(path, ptr, CVT_FLOAT, flags, min, max, notifyChanged) /// Same as C_VAR_CHARPTR() except allows specifying a callback function for -/// change notification. @ingroup console +/// change notification. @ingroup cvar #define C_VAR_CHARPTR2(path, ptr, flags, min, max, notifyChanged) \ C_VAR(path, ptr, CVT_CHARPTR, flags, min, max, notifyChanged) /// Same as C_VAR_URIPTR() except allows specifying a callback function for -/// change notification. @ingroup console +/// change notification. @ingroup cvar #define C_VAR_URIPTR2(path, ptr, flags, min, max, notifyChanged) \ C_VAR(path, ptr, CVT_URIPTR, flags, min, max, notifyChanged) diff --git a/doomsday/engine/api/doomsday.h b/doomsday/engine/api/doomsday.h index b8b090f4ad..0a6b6c2371 100644 --- a/doomsday/engine/api/doomsday.h +++ b/doomsday/engine/api/doomsday.h @@ -226,11 +226,13 @@ void Con_SetPrintFilter(con_textfilter_t filter); int DD_Execute(int silent, const char* command); int DD_Executef(int silent, const char* command, ...); +/// @addtogroup bindings +///@{ // Console: Bindings. void B_SetContextFallback(const char* name, int (*responderFunc)(event_t*)); int B_BindingsForCommand(const char* cmd, char* buf, size_t bufSize); int B_BindingsForControl(int localPlayer, const char* controlName, int inverse, char* buf, size_t bufSize); - +///@} //------------------------------------------------------------------------ // // System.