From d6bdeb049987e063e34ceb2acedc5be352e52521 Mon Sep 17 00:00:00 2001 From: Jason Felds Date: Sun, 13 Feb 2011 18:12:40 -0500 Subject: [PATCH] Another round of doxygenating. --- src/MsdFile.h | 2 +- src/PlayerState.h | 59 +++++++++++++++++++++++++++++++--------- src/Profile.cpp | 2 ++ src/Profile.h | 58 +++++++++++++++++++++++++--------------- src/Style.h | 68 ++++++++++++++++++++++++++++++++++------------- 5 files changed, 134 insertions(+), 55 deletions(-) diff --git a/src/MsdFile.h b/src/MsdFile.h index c03aedd54d..0b52d639ab 100644 --- a/src/MsdFile.h +++ b/src/MsdFile.h @@ -10,7 +10,7 @@ public: /** * @brief The list of params found in the files. * - * Note that #param:param:param:parm; is one whole value. */ + * Note that #param:param:param:param; is one whole value. */ struct value_t { /** @brief The list of parameters. */ diff --git a/src/PlayerState.h b/src/PlayerState.h index ac4f5f0749..26559e50f8 100644 --- a/src/PlayerState.h +++ b/src/PlayerState.h @@ -1,4 +1,4 @@ -/* PlayerState - Holds per-player game state. */ +/** @brief PlayerState - Holds per-player game state. */ #ifndef PlayerState_H #define PlayerState_H @@ -11,37 +11,68 @@ #include "SampleHistory.h" struct lua_State; +/** @brief The player's indivdual state. */ class PlayerState { public: + /** @brief Set up the PlayerState with initial values. */ PlayerState(); + /** @brief Reset the PlayerState with the initial values. */ void Reset(); + /** + * @brief Update the PlayerState based on the present time. + * @param fDelta the current time. */ void Update( float fDelta ); - // TODO: Remove use of PlayerNumber. All data about the player should live - // in PlayerState and callers should not use PlayerNumber to index into - // GameState. + /** + * @brief The PlayerNumber assigned to this Player: usually 1 or 2. + * + * TODO: Remove use of PlayerNumber. All data about the player should live + * in PlayerState and callers should not use PlayerNumber to index into + * GameState. */ PlayerNumber m_PlayerNumber; + MultiPlayer m_mp; + /** + * @brief Change the PlayerOptions to their default. + * @param l the level of mods to reset. + */ void ResetToDefaultPlayerOptions( ModsLevel l ); + /** @brief The PlayerOptions presently in use by the Player. */ ModsGroup m_PlayerOptions; - // Used in Gameplay - mutable float m_fLastDrawnBeat; // Set by NoteField. Used to push note-changing modifers back so that notes doesn't pop. - + /** + * @brief Used to push note-changing modifiers back so that notes don't pop. + * + * This is used during gameplay and set by NoteField. */ + mutable float m_fLastDrawnBeat; + /** @brief The Player's HealthState in general terms. */ HealthState m_HealthState; - float m_fLastStrumMusicSeconds; // Set to the MusicSeconds of when the a strum button was pressed. If -1, the strum window has passed. - float m_fLastHopoNoteMusicSeconds; // Set to the MusicSeconds of the last note successfully strummed or hammered in a hopochain, -1, then there is no current hopo chain - int m_iLastHopoNoteCol; // if -1, then there is no current hopo chain + /** + * @brief Set to the MusicSeconds of when the a strum button was pressed. + * + * If -1, the strum window has passed. */ + float m_fLastStrumMusicSeconds; + /** + * @brief Set to the MusicSeconds of the last note successfully strummed or hammered in a hopochain. + * + * If -1, then there is no current hopo chain. */ + float m_fLastHopoNoteMusicSeconds; + /** + * @brief Set to the column in the current hopo chain. + * + * If -1, then there is no current hopo chain. */ + int m_iLastHopoNoteCol; + /** @brief Reset the hopo state to its default. */ void ClearHopoState() { m_fLastHopoNoteMusicSeconds = -1; m_iLastHopoNoteCol = -1; } - + /** @brief The type of person/machine controlling the Player. */ PlayerController m_PlayerController; SampleHistory m_EffectHistory; @@ -80,8 +111,10 @@ public: #endif -/* - * (c) 2001-2004 Chris Danford, Chris Gomez +/** + * @file + * @author Chris Danford, 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/Profile.cpp b/src/Profile.cpp index 4f20cc7e5e..22b071a4d6 100644 --- a/src/Profile.cpp +++ b/src/Profile.cpp @@ -28,7 +28,9 @@ const RString STATS_XML = "Stats.xml"; const RString STATS_XML_GZ = "Stats.xml.gz"; +/** @brief The filename for where one can edit their personal profile information. */ const RString EDITABLE_INI = "Editable.ini"; +/** @brief The filename containing the signature for STATS_XML's signature. */ const RString DONT_SHARE_SIG = "DontShare.sig"; const RString PUBLIC_KEY_FILE = "public.key"; const RString SCREENSHOTS_SUBDIR = "Screenshots/"; diff --git a/src/Profile.h b/src/Profile.h index 9809c68467..b351656bd0 100644 --- a/src/Profile.h +++ b/src/Profile.h @@ -1,4 +1,4 @@ -/* Profile - Player data that persists between sessions. Can be stored on a local disk or on a memory card. */ +/** @brief Profile - Player data that persists between sessions. Can be stored on a local disk or on a memory card. */ #ifndef Profile_H #define Profile_H @@ -24,19 +24,25 @@ class Character; // Current file versions extern const RString STATS_XML; -// Editable data is an INI because the default INI file association on Windows -// systems will open the ini file in an editor. The default association for -// XML will open in IE. Users have a much better chance of discovering how to -// edit this data if they don't have to fight against the file associations. +/** + * @brief The filename where one can edit their personal profile data. + * + * Editable data is an INI because the default INI file association on Windows + * systems will open the ini file in an editor. The default association for + * XML will open in IE. Users have a much better chance of discovering how to + * edit this data if they don't have to fight against the file associations. */ extern const RString EDITABLE_INI; -// The "don't share" file is something that the user should always keep private. -// They can safely share STATS_XML with STATS_XML's signature so that others -// can authenticate the STATS_XML data. However, others can't copy that data -// to their own profile for use in the game unless they also have the "don't -// share" file. DontShare contains a piece of information that we can -// construct using STATS_XML but the user can't construct using STATS_XML. -// The file contains a signature of the STATS_XML's signature. +/** + * @brief The filename containing the signature for STATS_XML's signature. + * + * + * The "don't share" file is something that the user should always keep private. + * They can safely share STATS_XML with STATS_XML's signature so that others + * can authenticate the STATS_XML data. However, others can't copy that data + * to their own profile for use in the game unless they also have the "don't + * share" file. DontShare contains a piece of information that we can + * construct using STATS_XML but the user can't construct using STATS_XML. */ extern const RString DONT_SHARE_SIG; extern const RString PUBLIC_KEY_FILE; @@ -46,6 +52,7 @@ extern const RString EDIT_COURSES_SUBDIR; extern const RString LASTGOOD_SUBDIR; // extern const RString RIVAL_SUBDIR; +/** @brief The max number of characters that can be used in a profile. */ const unsigned int PROFILE_MAX_DISPLAY_NAME_LENGTH = 32; @@ -137,7 +144,10 @@ public: map m_iNumSongsPlayedByStyle; int m_iNumSongsPlayedByDifficulty[NUM_Difficulty]; int m_iNumSongsPlayedByMeter[MAX_METER+1]; - /* This stat counts once per song, even if two players are active. */ + /** + * @brief Count the total number of songs played. + * + * This stat counts once per song, even if two players are active. */ int m_iNumTotalSongsPlayed; int m_iNumStagesPassedByPlayMode[NUM_PlayMode]; int m_iNumStagesPassedByGrade[NUM_Grade]; @@ -206,13 +216,15 @@ public: int GetNextScreenshotIndex() { return m_vScreenshots.size(); } - // Calorie Data - // Why track calories in a map, and not in a static sized array like - // Bookkeeping? The machine's clock is not guaranteed to be set correctly. - // If calorie array is in a static sized array, playing on a machine with - // a mis-set clock could wipe out all your past data. With this scheme, - // the worst that could happen is that playing on a mis-set machine will - // insert some garbage entries into the map. + /** + * @brief The basics for Calorie Data + * + * Why track calories in a map, and not in a static sized array like + * Bookkeeping? The machine's clock is not guaranteed to be set correctly. + * If calorie array is in a static sized array, playing on a machine with + * a mis-set clock could wipe out all your past data. With this scheme, + * the worst that could happen is that playing on a mis-set machine will + * insert some garbage entries into the map. */ struct Calories { Calories() { fCals = 0; } @@ -315,8 +327,10 @@ private: #endif -/* - * (c) 2001-2004 Chris Danford +/** + * @file + * @author Chris Danford (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/Style.h b/src/Style.h index dbec066973..4c91746533 100644 --- a/src/Style.h +++ b/src/Style.h @@ -1,4 +1,4 @@ -/* Style - A data structure that holds the definition for one of a Game's styles. */ +/** @brief Style - A data structure that holds the definition for one of a Game's styles. */ #ifndef STYLE_H #define STYLE_H @@ -8,8 +8,9 @@ #include "PlayerNumber.h" #include "GameConstantsAndTypes.h" - +/** @brief Each style can have a maximum amount of columns to work with. */ const int MAX_COLS_PER_PLAYER = MAX_NOTE_TRACKS; +/** @brief Provide a default value for an invalid column. */ static const int Column_Invalid = -1; class NoteData; @@ -19,41 +20,68 @@ struct lua_State; class Style { public: - bool m_bUsedForGameplay; // Can be used only for gameplay? - bool m_bUsedForEdit; // Can be used for editing? - bool m_bUsedForDemonstration; // Can be used for demonstration? - bool m_bUsedForHowToPlay; // Can be used for HowToPlay? + /** @brief Can this style be used for gameplay purposes? */ + bool m_bUsedForGameplay; + /** @brief Can this style be used for making edits? */ + bool m_bUsedForEdit; + /** @brief Can this style be used in a demonstration? */ + bool m_bUsedForDemonstration; + /** @brief Can this style be used to explain how to play the game? */ + bool m_bUsedForHowToPlay; - // The name of the style. (This is currently unused.) + /** + * @brief The name of the style. + * + * At this time, it is currently unused. */ const char * m_szName; - /* Steps format used for each player. For example, "dance versus" reads - * the Steps with the tag "dance-single". */ + /** + * @brief Steps format used for each player. + * + * For example, "dance versus" reads the Steps with the tag "dance-single". */ StepsType m_StepsType; + /** @brief Style format used for each player. */ StyleType m_StyleType; - int m_iColsPerPlayer; // number of total tracks this style expects (e.g. 4 for versus, but 8 for double) + /** + * @brief The number of total tracks/columns this style expects. + * + * As an example, 4 is expected for ITG style versus, but 8 for ITG style double. */ + int m_iColsPerPlayer; + /** @brief Some general column infromation */ struct ColumnInfo { - int track; // take note data from this track - float fXOffset; // x position of the column relative to player center - const char *pzName; // name of this column, or NULL to use the name of a button mapped to it + int track; /**< Take note data from this track. */ + float fXOffset; /**< This is the x position of the column relative to the player's center. */ + const char *pzName; /**< The name of the column, or NULL to use the button name mapped to it. */ }; - ColumnInfo m_ColumnInfo[NUM_PLAYERS][MAX_COLS_PER_PLAYER]; // maps each players' column to a track in the NoteData + /** @brief Map each players' colun to a track in the NoteData. */ + ColumnInfo m_ColumnInfo[NUM_PLAYERS][MAX_COLS_PER_PLAYER]; /* This maps from game inputs to columns. More than one button may map to a * single column. */ enum { NO_MAPPING = -1, END_MAPPING = -2 }; - int m_iInputColumn[NUM_GameController][NUM_GameButton]; // maps each input to a column, or GameButton_Invalid + /** @brief Map each input to a column, or GameButton_Invalid. */ + int m_iInputColumn[NUM_GameController][NUM_GameButton]; int m_iColumnDrawOrder[MAX_COLS_PER_PLAYER]; + /** @brief Does this style need to be zoomed out with two players due to too many columns? */ bool m_bNeedsZoomOutWith2Players; + /** @brief Can this style use the BeginnerHelper for assisting new people to the game? */ bool m_bCanUseBeginnerHelper; - bool m_bLockDifficulties; // used in couple Styles + /** + * @brief Should difficulty selection be locked when using this style? + * + * This is primarily for Couple and Routine styles. */ + bool m_bLockDifficulties; GameInput StyleInputToGameInput( int iCol, PlayerNumber pn ) const; - // Returns Column_Invalid if the input is an invalid column, such as UL corner in 4 pad mode + /** + * @brief Retrieve the column based on the game input. + * @param GameI the game input. + * @return the Column number of the style, or Column_Invalid if it's an invalid column. + * Examples of this include getting the upper left hand corner in a traditional four panel mode. */ int GameInputToColumn( const GameInput &GameI ) const; RString ColToButtonName( int iCol ) const; @@ -68,8 +96,10 @@ public: #endif -/* - * (c) 2001-2002 Chris Danford +/** + * @file + * @author Chris Danford (c) 2001-2002 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a