diff --git a/src/CommandLineActions.cpp b/src/CommandLineActions.cpp index e073afb7df..7d852d1f76 100644 --- a/src/CommandLineActions.cpp +++ b/src/CommandLineActions.cpp @@ -24,6 +24,7 @@ #include #endif +/** @brief The directory where languages should be installed. */ const RString INSTALLER_LANGUAGES_DIR = "Themes/_Installer/Languages/"; vector CommandLineActions::ToProcess; @@ -82,11 +83,14 @@ extern const char *const version_date; extern const char *const version_time; #endif +/** + * @brief Print out version information. + * + * HACK: This function is primarily needed for Windows users. + * Mac OS X and Linux print out version information on the command line + * regardless of any preferences (tested by shakesoda on Mac). -aj */ static void Version() { - /* HACK: This is only needed on Windows. - Mac and Linux print out version information on the command line regardless - of any preferences (tested by shakesoda on Mac). -aj */ #if defined(WIN32) RString sProductID = ssprintf("%s", PRODUCT_ID_VER); RString sVersion = "(sm-ssc was built without HAVE_VERSION_INFO)"; diff --git a/src/CommandLineActions.h b/src/CommandLineActions.h index 805508912e..fdbaef8919 100644 --- a/src/CommandLineActions.h +++ b/src/CommandLineActions.h @@ -3,25 +3,34 @@ class LoadingWindow; +/** @brief The collection of command line actions. */ namespace CommandLineActions { - void Handle(LoadingWindow* pLW); // perform a utility action, then exit + /** + * @brief Perform a utility function, then exit. + * @param pLW the LoadingWindow that is presently not used? */ + void Handle(LoadingWindow* pLW); + /** @brief The housing for the command line arguments. */ class CommandLineArgs { public: + /** @brief the arguments in question. */ vector argv; }; - // a list of command line arguemnts to process while the game is running. - // These args could have come from this process or passed to this process - // from another process. + /** + * @brief A list of command line arguemnts to process while the game is running. + * These args could have come from this process or passed to this process + * from another process. */ extern vector ToProcess; } #endif -/* - * (c) 2006 Chris Danford, Steve Checkoway +/** + * @file + * @author Chris Danford, Steve Checkoway (c) 2006 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/GameState.h b/src/GameState.h index bb1285f0cb..370f789a6c 100644 --- a/src/GameState.h +++ b/src/GameState.h @@ -1,4 +1,4 @@ -/* GameState - Holds game data that is not saved between sessions. */ +/** @brief GameState - Holds game data that is not saved between sessions. */ #ifndef GAMESTATE_H #define GAMESTATE_H @@ -36,8 +36,10 @@ class Trail; class GameState { public: + /** @brief Set up the GameState with initial values. */ GameState(); ~GameState(); + /** @brief Reset the GameState back to initial values. */ void Reset(); void ResetPlayer( PlayerNumber pn ); void ApplyCmdline(); // called by Reset @@ -63,11 +65,21 @@ public: void SetCurGame( const Game *pGame ); // Call this instead of m_pCurGame.Set to make sure PREFSMAN->m_sCurrentGame stays in sync BroadcastOnChangePtr m_pCurGame; BroadcastOnChangePtr m_pCurStyle; + /** @brief Determine which side is joined. + * + * The left side is player 1, and the right side is player 2. */ bool m_bSideIsJoined[NUM_PLAYERS]; // left side, right side MultiPlayerStatus m_MultiPlayerStatus[NUM_MultiPlayer]; BroadcastOnChange m_PlayMode; // many screens display different info depending on this value - BroadcastOnChange m_iCoins; // not "credits" - PlayerNumber m_MasterPlayerNumber; // used in Styles where one player controls both sides + /** + * @brief The number of coins presently in the machine. + * + * Note that coins are not "credits". One may have to put in two coins + * to get one credit, only to have to put in another four coins to get + * the three credits needed to begin the game. */ + BroadcastOnChange m_iCoins; + /** @brief The player number used with Styles where one player controls both sides. */ + PlayerNumber m_MasterPlayerNumber; bool m_bMultiplayer; int m_iNumMultiplayerNoteFields; bool DifficultiesLocked() const; @@ -86,7 +98,10 @@ public: int m_iGameSeed, m_iStageSeed; RString m_sStageGUID; - bool PlayersCanJoin() const; // true if it's not too late for a player to join + /** + * @brief Determine if a second player can join in at this time. + * @return true if a player can still enter the game, false otherwise. */ + bool PlayersCanJoin() const; int GetCoinsNeededToJoin() const; bool EnoughCreditsToJoin() const { return m_iCoins >= GetCoinsNeededToJoin(); } int GetNumSidesJoined() const; @@ -127,9 +142,15 @@ public: bool m_bDemonstrationOrJukebox; // ScreenGameplay does special stuff when this is true bool m_bJukeboxUsesModifiers; int m_iNumStagesOfThisSong; - // Increases every stage, doesn't reset when player continues. It's cosmetic and not used in Stage or Screen branching logic. + /** + * @brief Increase this every stage while not resetting on a continue. + * + * This is cosmetic: it's not use for Stage or Screen branching logic. */ int m_iCurrentStageIndex; - // Num stages available for player. Resets when player joins/continues. + /** + * @brief The number of stages available for the players. + * + * This resets whenever a player joins or continues. */ int m_iPlayerStageTokens[NUM_PLAYERS]; static int GetNumStagesMultiplierForSong( const Song* pSong ); @@ -182,8 +203,10 @@ public: float m_fCurBPS; float m_fLightSongBeat; // g_fLightsFalloffSeconds ahead //bool m_bStop; // in the middle of a stop (freeze or delay) - bool m_bFreeze; // in the middle of a freeze - bool m_bDelay; // in the middle of a delay + /** @brief A flag to determine if we're in the middle of a freeze/stop. */ + bool m_bFreeze; + /** @brief A flag to determine if we're in the middle of a delay (Pump style stop). */ + bool m_bDelay; // used for warping: int m_iWarpBeginRow; float m_fWarpLength; @@ -229,11 +252,13 @@ public: bool m_bGoalComplete[NUM_PLAYERS]; bool m_bWorkoutGoalComplete; - void RemoveAllActiveAttacks(); // called on end of song + /** @brief Primarily called at the end of a song to stop all attacks. */ + void RemoveAllActiveAttacks(); PlayerNumber GetBestPlayer() const; StageResult GetStageResult( PlayerNumber pn ) const; - void ResetStageStatistics(); // Call this when it's time to play a new stage. + /** @brief Call this function when it's time to play a new stage. */ + void ResetStageStatistics(); // Options stuff ModsGroup m_SongOptions; @@ -291,6 +316,7 @@ public: void VisitAttractScreen( const RString sScreenName ); // PlayerState + /** @brief Allow access to each player's PlayerState. */ PlayerState* m_pPlayerState[NUM_PLAYERS]; PlayerState* m_pMultiPlayerState[NUM_MultiPlayer]; @@ -346,8 +372,10 @@ extern GameState* GAMESTATE; // global and accessable from anywhere in our progr #endif -/* - * (c) 2001-2004 Chris Danford, Glenn Maynard, Chris Gomez +/** + * @file + * @author Chris Danford, Glenn Maynard, Chris Gomez (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/IniFile.h b/src/IniFile.h index 7e45a9ec58..5a468c41d2 100644 --- a/src/IniFile.h +++ b/src/IniFile.h @@ -1,4 +1,4 @@ -/* IniFile - Reading and writing .INI files. */ +/** @brief IniFile - Reading and writing .INI files. */ #ifndef INIFILE_H #define INIFILE_H @@ -7,14 +7,20 @@ using namespace std; class RageFileBasic; - +/** @brief The functions to read and write .INI files. */ class IniFile : public XNode { public: + /** @brief Set up an INI file with the defaults. */ IniFile(); - // Retrieve the filename of the last file loaded. + /** + * @brief Retrieve the filename of the last file loaded. + * @return the filename. */ RString GetPath() const { return m_sPath; } + /** + * @brief Retrieve any errors that have occurred. + * @return the latest error. */ const RString &GetError() const { return m_sError; } bool ReadFile( const RString &sPath ); @@ -42,9 +48,15 @@ public: bool DeleteKey( const RString &keyname ); bool DeleteValue( const RString &keyname, const RString &valuename ); - /* Rename a key. For example, call RenameKey("foo", "main") after - * reading an INI where [foo] is an alias to [main]. If to already - * exists, nothing happens. */ + /** + * @brief Rename a key. + * + * For example, call RenameKey("foo", "main") after reading an INI + * where [foo] is an alias to [main]. If to already exists, + * nothing happens. + * @param from the key to rename. + * @param to the new key name. + * @return its success or failure. */ bool RenameKey( const RString &from, const RString &to ); private: @@ -55,9 +67,10 @@ private: #endif -/* - * (c) 2001-2004 Adam Clauss, Chris Danford - * +/** + * @file + * @author Adam Clauss, Chris Danford (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a