Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Documentation: Various fixes
@see is not appropriate inside @param list as it produces
a "See also" section. It's better to use @ref.

Fixed group definitions and added a Flags group in which
the other flags are subgrouped.
  • Loading branch information
skyjake committed Jan 12, 2012
1 parent f9ac309 commit 2054b29
Show file tree
Hide file tree
Showing 7 changed files with 42 additions and 29 deletions.
2 changes: 1 addition & 1 deletion doomsday/doomsday.doxy
Expand Up @@ -65,7 +65,7 @@ INLINE_INFO = YES
SORT_MEMBER_DOCS = YES
SORT_BRIEF_DOCS = NO
SORT_MEMBERS_CTORS_1ST = NO
SORT_GROUP_NAMES = NO
SORT_GROUP_NAMES = YES
SORT_BY_SCOPE_NAME = NO
STRICT_PROTO_MATCHING = NO
GENERATE_TODOLIST = YES
Expand Down
8 changes: 4 additions & 4 deletions doomsday/engine/api/dd_fontrenderer.h
Expand Up @@ -167,8 +167,8 @@ void FR_SetCaseScale(boolean value);
*
* @param text Block of text to be drawn.
* @param origin Orient drawing about this offset (topleft:[0,0]).
* @param alignFlags @see alignmentFlags
* @param flags @see drawTextFlags
* @param alignFlags @ref alignmentFlags
* @param flags @ref drawTextFlags
*/
void FR_DrawText3(const char* text, const Point2Raw* origin, int alignFlags, short flags);
void FR_DrawText2(const char* text, const Point2Raw* origin, int alignFlags);
Expand All @@ -195,8 +195,8 @@ int FR_TextHeight(const char* text);
* @param ch Character to be drawn.
* @param x X origin/offset at which to begin drawing.
* @param y Y origin/offset at which to begin drawing.
* @param alignFlags @see alignmentFlags
* @param flags @see drawTextFlags
* @param alignFlags @ref alignmentFlags
* @param flags @ref drawTextFlags
*/
void FR_DrawChar3(unsigned char ch, const Point2Raw* origin, int alignFlags, short flags);
void FR_DrawChar2(unsigned char ch, const Point2Raw* origin, int alignFlags);
Expand Down
7 changes: 4 additions & 3 deletions doomsday/engine/api/dd_infine.h
Expand Up @@ -35,7 +35,8 @@
typedef ident_t finaleid_t;

/**
* @defgroup finaleFlags Finale Flags.
* @defgroup finaleFlags Finale Flags
* @ingroup apiFlags
*/
/*@{*/
#define FF_LOCAL 0x1 /// Local scripts are executed client-side.
Expand All @@ -44,7 +45,7 @@ typedef ident_t finaleid_t;
/**
* Execute a set of Finale commands.
* @param script One or more commands to be executed.
* @param flags @see finaleFlags.
* @param flags @ref finaleFlags.
* @param setupCmds One or more commands to be executed immediately during
* finale setup. Can be used to configure the default page
* state.
Expand All @@ -58,7 +59,7 @@ finaleid_t FI_Execute(const char* script, int flags);
boolean FI_ScriptActive(finaleid_t id);

/**
* @return @see finaleFlags.
* @return @ref finaleFlags.
*/
int FI_ScriptFlags(finaleid_t id);

Expand Down
38 changes: 25 additions & 13 deletions doomsday/engine/api/dd_share.h
Expand Up @@ -359,12 +359,15 @@ typedef struct gameinfo_s {
const char* identityKey;
} GameInfo;

/// @defgroup apiFlags Flags

/**
* @defgroup resourceFlags ResourceFlags
* @defgroup resourceFlags Resource Flags
* @ingroup apiFlags
*/
/*{@*/
///@{
#define RF_STARTUP 0x1 // A required resource needed for and loaded during game start up (can't be a virtual file).
/*}@*/
///@}

//------------------------------------------------------------------------
//
Expand Down Expand Up @@ -744,7 +747,8 @@ typedef struct {
} fdivline_t;

/**
* @defgroup pathTraverseFlags Path Traverse Flags.
* @defgroup pathTraverseFlags Path Traverse Flags
* @ingroup apiFlags
* @{
*/
#define PT_ADDLINES 1 /// Intercept with LineDefs.
Expand All @@ -761,6 +765,7 @@ typedef enum {
/**
* @defgroup lineSightFlags Line Sight Flags
* Flags used to dictate logic within P_CheckLineSight.
* @ingroup apiFlags
*/
/*@{*/
#define LS_PASSLEFT 0x1 // Ray may cross one-sided linedefs from left to right.
Expand Down Expand Up @@ -994,7 +999,8 @@ typedef struct aaboxf_s {
#define SCREENHEIGHT 200

/**
* @defgroup alignmentFlags Alignment Flags.
* @defgroup alignmentFlags Alignment Flags
* @ingroup apiFlags
*/
/*@{*/
#define ALIGN_LEFT (0x1)
Expand Down Expand Up @@ -1025,7 +1031,8 @@ typedef enum {
#define DEFAULT_SCALEMODE_STRETCH_EPSILON (.38f)

/**
* @defgroup borderedProjectionFlags Bordered Projection Flags.
* @defgroup borderedProjectionFlags Bordered Projection Flags
* @ingroup apiFlags
* @{
*/
#define BPF_OVERDRAW_MASK 0x1
Expand Down Expand Up @@ -1073,6 +1080,7 @@ typedef struct {

/**
* @defgroup materialFlags Material Flags
* @ingroup apiFlags
* @{
*/
//#define MATF_UNUSED1 0x1
Expand All @@ -1084,6 +1092,7 @@ typedef struct {

/**
* @defgroup animationGroupFlags Animation Group Flags
* @ingroup apiFlags
* @{
*/
#define AGF_SMOOTH 0x1
Expand Down Expand Up @@ -1239,7 +1248,8 @@ typedef unsigned int colorpaletteid_t;
#define BUSYF_TRANSITION 0x40 // Do a transition effect when busy mode ends.

/**
* @defgroup consolePrintFlags Console Print Flags.
* @defgroup consolePrintFlags Console Print Flags
* @ingroup apiFlags
*/
/*@{*/
// These correspond the good old text mode VGA colors.
Expand All @@ -1265,7 +1275,8 @@ typedef enum bfcinverse_e {
} bfcinverse_t;

/**
* @defgroup consoleCommandFlags Console command flags.
* @defgroup consoleCommandFlags Console Command Flags
* @ingroup apiFlags
*/
/*@{*/
#define CMDF_NO_NULLGAME 0x00000001 // Not available unless a game is loaded.
Expand Down Expand Up @@ -1314,7 +1325,7 @@ typedef struct ccmdtemplate_s {
/// Execute function.
int (*execFunc) (byte src, int argc, char** argv);

/// @see consoleCommandFlags
/// @ref consoleCommandFlags
int flags;
} ccmdtemplate_t;

Expand All @@ -1331,7 +1342,8 @@ typedef struct ccmdtemplate_s {
{ ccmdtemplate_t _template = { name, argTemplate, CCmd##fn, flags }; Con_AddCommand(&_template); }

/**
* @defgroup consoleVariableFlags Console Variable flags.
* @defgroup consoleVariableFlags Console Variable Flags
* @ingroup apiFlags
*/
/*@{*/
#define CVF_NO_ARCHIVE 0x1 // Not written in/read from the defaults file.
Expand All @@ -1344,7 +1356,7 @@ typedef struct ccmdtemplate_s {
/*@}*/

/**
* @defgroup setVariableFlags Set Variable Flags.
* @defgroup setVariableFlags Set Variable Flags
*
* Use with the various Con_Set* routines (e.g., Con_SetInteger2).
*/
Expand Down Expand Up @@ -1372,7 +1384,7 @@ typedef struct cvartemplate_s {
/// Path of the variable.
const char* path;

/// @see consoleVariableFlags
/// @ref consoleVariableFlags
int flags;

/// Type of variable.
Expand Down Expand Up @@ -1616,7 +1628,7 @@ typedef struct ticcmd_s {
int tics;
float alpha;
float pos[2];
byte flags; // @see pspriteFlags
byte flags; /// @ref pspriteFlags
int state;
float offset[2];
} ddpsprite_t;
Expand Down
4 changes: 2 additions & 2 deletions doomsday/engine/api/dd_string.h
Expand Up @@ -190,7 +190,7 @@ int Str_Strip(ddstring_t* ds);
const char* Str_GetLine(ddstring_t* ds, const char* src);

/**
* @defGroup copyDelimiterFlags Copy Delimiter Flags.
* @defGroup copyDelimiterFlags Copy Delimiter Flags
*/
/*@{*/
#define CDF_OMIT_DELIMITER 0x1 // Do not copy delimiters into the dest path.
Expand All @@ -203,7 +203,7 @@ const char* Str_GetLine(ddstring_t* ds, const char* src);
* @param dest Destination string.
* @param src Source string.
* @param delimiter Delimiter character.
* @param flags @see copyDelimiterFlags.
* @param flags @ref copyDelimiterFlags
*
* @return Pointer to the character within @a src where copy stopped
* else @c NULL if the end was reached.
Expand Down
4 changes: 2 additions & 2 deletions doomsday/engine/api/dd_ui.h
Expand Up @@ -272,8 +272,8 @@ typedef struct fidata_text_s {
FIOBJECT_BASE_ELEMENTS()
animatorvector4_t color;
uint pageColor; /// Identifier of the owning page's predefined color. Zero means use our own color.
int alignFlags; /// @see alignmentFlags
short textFlags; /// @see drawTextFlags
int alignFlags; /// @ref alignmentFlags
short textFlags; /// @ref drawTextFlags
int scrollWait, scrollTimer; /// Automatic scrolling upwards.
size_t cursorPos;
int wait, timer;
Expand Down
8 changes: 4 additions & 4 deletions doomsday/engine/api/doomsday.h
Expand Up @@ -107,15 +107,15 @@ gameid_t DD_GameIdForKey(const char* identityKey);
/**
* Registers a new resource for the specified game.
*
* \note Resource registration order defines the load order of resources
* (among those of the same type).
*
* @param game Unique identifier/name of the game.
* @param rclass Class of resource being added.
* @param rflags @see resourceFlags
* @param rflags Resource flags (see @ref resourceFlags).
* @param names One or more known potential names, seperated by semicolon e.g., "name1;name2".
* Names may include valid absolute, or relative file paths. These paths include
* valid symbolbolic escape tokens, predefined symbols into the virtual file system.
*
* \note Resource registration order defines the load order of resources
* (among those of the same type).
*/
void DD_AddGameResource(gameid_t game, resourceclass_t rclass, int rflags, const char* names, void* params);

Expand Down

0 comments on commit 2054b29

Please sign in to comment.