From e9449cb50e1c91b5a4b8ed13b50ad3d7c91ebead Mon Sep 17 00:00:00 2001 From: Jason Felds Date: Sat, 19 Feb 2011 17:00:32 -0500 Subject: [PATCH] More doxy, more recompiling all. --- src/ActiveAttackList.h | 20 ++++++++++++++------ src/Actor.cpp | 5 ++++- src/Actor.h | 17 ++++++++++++++--- src/Grade.cpp | 1 + src/Grade.h | 32 +++++++++++++++++++++++--------- src/GradeDisplay.h | 4 +--- src/GraphDisplay.h | 2 +- src/GrooveRadar.h | 10 +++++----- src/HelpDisplay.h | 4 +--- src/ModIcon.h | 4 +--- src/ProfileManager.h | 4 +--- src/global.h | 33 +++++++++++++++++++++++++++------ 12 files changed, 93 insertions(+), 43 deletions(-) diff --git a/src/ActiveAttackList.h b/src/ActiveAttackList.h index 169f1af1ff..38589c8840 100644 --- a/src/ActiveAttackList.h +++ b/src/ActiveAttackList.h @@ -1,29 +1,37 @@ -/* ActiveAttackList - Shows currently active player modifiers during gameplay. */ #ifndef ACTIVE_ATTACK_LIST_H #define ACTIVE_ATTACK_LIST_H #include "BitmapText.h" class PlayerState; +/** @brief Shows currently active Player modifiers during gameplay. */ class ActiveAttackList : public BitmapText { public: + /** @brief The constructor that does nothing. */ ActiveAttackList(); - + /** + * @brief Set up the PlayerState. + * @param pPlayerState the PlayerState involved with the attacks. */ void Init( const PlayerState* pPlayerState ); - + /** + * @brief Look into updating the list. + * @param fDelta the present time. */ virtual void Update( float fDelta ); - + /** @brief Refresh the list of attacks. */ void Refresh(); protected: + /** @brief the PlayerState of the Player who is dealing with the attack list. */ const PlayerState* m_pPlayerState; }; #endif -/* - * (c) 2004 Chris Danford +/** + * @file + * @author Chris Danford (c) 2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/Actor.cpp b/src/Actor.cpp index ac61bb1e85..241b79dfb1 100644 --- a/src/Actor.cpp +++ b/src/Actor.cpp @@ -18,7 +18,10 @@ static Preference g_bShowMasks("ShowMasks", false); -/* It's useful to be able to construct a basic Actor in XML, in +/** + * @brief Set up a hidden Actor that won't be drawn. + * + * It's useful to be able to construct a basic Actor in XML, in * order to simply delay a Transition, or receive and send broadcasts. * Since these actors will never draw, set them hidden by default. */ class HiddenActor: public Actor diff --git a/src/Actor.h b/src/Actor.h index 14375c2994..e67278602b 100644 --- a/src/Actor.h +++ b/src/Actor.h @@ -1,5 +1,3 @@ -/** @brief Actor - Base class for all objects that appear on the screen. */ - #ifndef ACTOR_H #define ACTOR_H @@ -65,10 +63,11 @@ LuaDeclareType( VertAlign ); #define align_middle 0.5f /** @brief The bottom vertical alignment constant. */ #define align_bottom 1.0f - +/** @brief Base class for all objects that appear on the screen. */ class Actor : public MessageSubscriber { public: + /** @brief Set up the Actor with its initial settings. */ Actor(); Actor( const Actor &cpy ); virtual ~Actor(); @@ -158,9 +157,21 @@ public: virtual void UpdateInternal( float fDeltaTime ); // override this void UpdateTweening( float fDeltaTime ); + /** + * @brief Retrieve the Actor's name. + * @return the Actor's name. */ const RString &GetName() const { return m_sName; } + /** + * @brief Set the Actor's name to a new one. + * @param sName the new name for the Actor. */ virtual void SetName( const RString &sName ) { m_sName = sName; } + /** + * @brief Give this Actor a new parent. + * @param pParent the new parent Actor. */ void SetParent( Actor *pParent ); + /** + * @brief Retrieve the Actor's parent. + * @return the Actor's parent. */ Actor *GetParent() { return m_pParent; } RString GetLineage() const; diff --git a/src/Grade.cpp b/src/Grade.cpp index 7eaa651dd5..4506b16e49 100644 --- a/src/Grade.cpp +++ b/src/Grade.cpp @@ -8,6 +8,7 @@ LuaXType( Grade ); +/** @brief The current number of grade tiers being used. */ ThemeMetric NUM_GRADE_TIERS_USED("PlayerStageStats","NumGradeTiersUsed"); Grade GetNextPossibleGrade( Grade g ) diff --git a/src/Grade.h b/src/Grade.h index bf56b3a17f..f913eac8ed 100644 --- a/src/Grade.h +++ b/src/Grade.h @@ -1,5 +1,3 @@ -/** @brief Grade - Mark the player receives after clearing a song. */ - #ifndef GRADE_H #define GRADE_H @@ -7,12 +5,10 @@ #include "EnumHelper.h" #include "ThemeMetric.h" -/** - * @brief Have a specific number of passing grade tiers. +/** @brief The list of grading tiers available. * - * TODO: Look into flexible grading tiers. */ -#define NUM_Grade_TierS 20 -/** @brief The list of grading tiers available. */ + * TODO: Look into a more flexible system without a fixed number of grades. -Wolfman2000 + */ enum Grade { Grade_Tier01, /**< Usually an AAAA */ @@ -39,6 +35,7 @@ enum Grade NUM_Grade, Grade_Invalid, }; +/** @brief Have an alternative for if there is no data for grading. */ #define Grade_NoData Grade_Invalid /** @@ -61,15 +58,32 @@ static inline RString GradeToString( Grade g ) } } -RString GradeToOldString( Grade g ); // "AAA", "B", etc for backward compatibility. Used in announcer +/** + * @brief Convert to the old version styled grade strings. + * + * This is mainly for backward compatibility purposes, but the announcer + * also uses it. Think "AAA", "B", etc. + * @param g the current Grade. + * @return the old styled grade string. */ +RString GradeToOldString( Grade g ); RString GradeToLocalizedString( Grade g ); +/** + * @brief Convert the given RString into a proper Grade. + * @param s the string to convert. + * @return the expected Grade. + */ Grade StringToGrade( const RString &s ); LuaDeclareType( Grade ); extern ThemeMetric NUM_GRADE_TIERS_USED; #define NUM_POSSIBLE_GRADES (NUM_GRADE_TIERS_USED+1) +/** + * @brief Step through the enumerator one at a time to get the next Grade. + * @param g the current Grade. + * @return the next Grade. */ Grade GetNextPossibleGrade( Grade g ); /** @brief Loop through each possible Grade. */ -#define FOREACH_PossibleGrade( g ) for( Grade g = (Grade)(0); g != Grade_Invalid; g = GetNextPossibleGrade(g) ) +#define FOREACH_PossibleGrade( g ) \ +for( Grade g = (Grade)(0); g != Grade_Invalid; g = GetNextPossibleGrade(g) ) #endif diff --git a/src/GradeDisplay.h b/src/GradeDisplay.h index 5fbff846ea..4e16bab5aa 100644 --- a/src/GradeDisplay.h +++ b/src/GradeDisplay.h @@ -1,5 +1,3 @@ -/* GradeDisplay - Grade shown on ScreenEvaluation. */ - #ifndef GRADE_DISPLAY_H #define GRADE_DISPLAY_H @@ -8,7 +6,7 @@ #include "PlayerNumber.h" #include "AutoActor.h" struct lua_State; - +/** @brief Grade shown on ScreenEvaluation. */ class GradeDisplay : public ActorFrame { public: diff --git a/src/GraphDisplay.h b/src/GraphDisplay.h index 6931ac5647..a17bbe108e 100644 --- a/src/GraphDisplay.h +++ b/src/GraphDisplay.h @@ -1,4 +1,3 @@ -/* GraphDisplay - A graph of the player's life over the course of Gameplay, used on Evaluation. */ #ifndef GRAPH_DISPLAY_H #define GRAPH_DISPLAY_H @@ -9,6 +8,7 @@ class StageStats; class PlayerStageStats; class GraphLine; class GraphBody; +/** @brief A graph of the player's life over the course of Gameplay, used on Evaluation. */ class GraphDisplay: public ActorFrame { public: diff --git a/src/GrooveRadar.h b/src/GrooveRadar.h index 0df4108aaf..0cd6ba3d57 100644 --- a/src/GrooveRadar.h +++ b/src/GrooveRadar.h @@ -1,5 +1,3 @@ -/* GrooveRadar - The song's GrooveRadar displayed in SelectMusic. */ - #ifndef GROOVE_RADAR_H #define GROOVE_RADAR_H @@ -10,7 +8,7 @@ #include "GameConstantsAndTypes.h" class Steps; struct RadarValues; - +/** @brief The song's GrooveRadar displayed in SelectMusic. */ class GrooveRadar : public ActorFrame { public: @@ -26,8 +24,10 @@ public: void PushSelf( lua_State *L ); protected: - - // the value map must be a separate Actor so we can tween it separately from the labels + /** + * @brief The companion ValueMap to the GrooveRadar. + * + * This must be a separate Actor so that it can be tweened separately from the labels. */ class GrooveRadarValueMap : public ActorFrame { public: diff --git a/src/HelpDisplay.h b/src/HelpDisplay.h index 6a5a0f9dcf..e9d0edfe9c 100644 --- a/src/HelpDisplay.h +++ b/src/HelpDisplay.h @@ -1,12 +1,10 @@ -/* HelpDisplay - A BitmapText that cycles through messages. */ - #ifndef HELP_DISPLAY_H #define HELP_DISPLAY_H #include "BitmapText.h" struct lua_State; - +/** @brief A BitmapText that cycles through messages. */ class HelpDisplay : public BitmapText { public: diff --git a/src/ModIcon.h b/src/ModIcon.h index 34911b8935..7596cdca79 100644 --- a/src/ModIcon.h +++ b/src/ModIcon.h @@ -1,5 +1,3 @@ -/* ModIcon - Shows PlayerOptions and SongOptions in icon form. */ - #ifndef ModIcon_H #define ModIcon_H @@ -8,7 +6,7 @@ #include "BitmapText.h" #include "PlayerNumber.h" #include "ThemeMetric.h" - +/** @brief Shows PlayerOptions and SongOptions in icon form. */ class ModIcon : public ActorFrame { public: diff --git a/src/ProfileManager.h b/src/ProfileManager.h index 3381b9498f..2f0ca9a9b5 100644 --- a/src/ProfileManager.h +++ b/src/ProfileManager.h @@ -1,5 +1,3 @@ -/* ProfileManager - Interface to machine and memory card profiles. */ - #ifndef ProfileManager_H #define ProfileManager_H @@ -17,7 +15,7 @@ class Course; class Trail; struct HighScore; struct lua_State; - +/** @brief Interface to machine and memory card profiles. */ class ProfileManager { public: diff --git a/src/global.h b/src/global.h index a2bc4c8ce1..e2e0a3d949 100644 --- a/src/global.h +++ b/src/global.h @@ -87,7 +87,9 @@ namespace Checkpoints { void SetCheckpoint( const char *file, int line, const char *message ); } +/** @brief Set a checkpoint with no message. */ #define CHECKPOINT (Checkpoints::SetCheckpoint(__FILE__, __LINE__, NULL)) +/** @brief Set a checkpoint with a specified message. */ #define CHECKPOINT_M(m) (Checkpoints::SetCheckpoint(__FILE__, __LINE__, m)) @@ -105,12 +107,24 @@ namespace Checkpoints #define NORETURN #endif +/** + * @brief A crash has occured, and we're not getting out of it easily. + * + * For most users, this will result in a crashinfo.txt file being generated. + * For anyone that is using a debug build, a debug break will be thrown to + * allow viewing the current process. + * @param reason the crash reason as determined by prior function calls. + * @return nothing: there is no escape without quitting the program. + */ void NORETURN sm_crash( const char *reason = "Internal error" ); -/* Assertion that sets an optional message and brings up the crash handler, so - * we get a backtrace. This should probably be used instead of throwing an - * exception in most cases we expect never to happen (but not in cases that - * we do expect, such as DSound init failure.) */ +/** + * @brief Assertion that sets an optional message and brings up the crash + * handler, so we get a backtrace. + * + * This should probably be used instead of throwing an exception in most + * cases we expect never to happen (but not in cases that we do expect, + * such as DSound init failure.) */ #define FAIL_M(MESSAGE) do { CHECKPOINT_M(MESSAGE); sm_crash(MESSAGE); } while(0) #define ASSERT_M(COND, MESSAGE) do { if(unlikely(!(COND))) { FAIL_M(MESSAGE); } } while(0) #if !defined(CO_EXIST_WITH_MFC) @@ -130,7 +144,9 @@ void ShowWarningOrTrace( const char *file, int line, const char *message, bool b #define DEBUG_ASSERT(x) ASSERT(x) #define DEBUG_ASSERT_M(x,y) ASSERT_M(x,y) #else +/** @brief A dummy define to keep things going smoothly. */ #define DEBUG_ASSERT(x) +/** @brief A dummy define to keep things going smoothly. */ #define DEBUG_ASSERT_M(x,y) #endif @@ -150,23 +166,28 @@ template struct CompileAssertDecl { }; #define COMPILE_ASSERT(COND) typedef CompileAssertDecl< sizeof(CompileAssert) > CompileAssertInst #if defined(__GNUC__) -/** @brief Define a macro to tell the compiler that a function has printf() semantics, to aid warning output. */ +/** @brief Define a macro to tell the compiler that a function has printf() + * semantics, to aid warning output. */ #define PRINTF(a,b) __attribute__((format(__printf__,a,b))) #define CONST_FUNCTION __attribute__((const)) #else +/** @brief A dummy define to keep things going smoothly. */ #define PRINTF(a,b) +/** @brief A dummy define to keep things going smoothly. */ #define CONST_FUNCTION #endif #if defined(__GNUC__) #define SM_ALIGN(n) __attribute__((aligned(n))) #else +/** @brief A dummy define to keep things going smoothly. */ #define SM_ALIGN(n) #endif -/** @brief Use RStrings throughout the program. */ + #include "StdString.h" +/** @brief Use RStrings throughout the program. */ typedef StdString::CStdString RString; #include "RageException.h"