From 0bf66667049ef8f53cdc275089c6d86c7a95be5a Mon Sep 17 00:00:00 2001 From: Jason Felds Date: Fri, 25 Feb 2011 19:28:00 -0500 Subject: [PATCH] More doxygen. --- src/GameInput.h | 41 ++++++++++++++++++---------- src/GameplayAssist.h | 2 -- src/GrooveRadar.h | 15 ++++++++--- src/HighScore.h | 3 +++ src/Song.h | 63 ++++++++++++++++++++++++++++++++++++++------ 5 files changed, 97 insertions(+), 27 deletions(-) diff --git a/src/GameInput.h b/src/GameInput.h index 0872a04860..fcdb61bf0e 100644 --- a/src/GameInput.h +++ b/src/GameInput.h @@ -1,5 +1,3 @@ -/* GameInput - An input event specific to an InputScheme defined by a logical controller and button. */ - #ifndef GAME_INPUT_H #define GAME_INPUT_H @@ -7,27 +5,29 @@ class InputScheme; +/** @brief the list of controllers in use. */ enum GameController { - GameController_1 = 0, // left controller - GameController_2, // right controller - NUM_GameController, // leave this at the end + GameController_1 = 0, /**< The left controller */ + GameController_2, /**< The right controller */ + NUM_GameController, /**< The number of controllers allowed. */ GameController_Invalid, }; const RString& GameControllerToString( GameController mp ); LuaDeclareType( GameController ); +/** @brief the list of buttons StepMania recognizes. */ enum GameButton { - GAME_BUTTON_MENULEFT, - GAME_BUTTON_MENURIGHT, - GAME_BUTTON_MENUUP, - GAME_BUTTON_MENUDOWN, + GAME_BUTTON_MENULEFT, /**< Navigate the menus to the left. */ + GAME_BUTTON_MENURIGHT, /**< Navigate the menus to the right. */ + GAME_BUTTON_MENUUP, /**< Navigate the menus to the top. */ + GAME_BUTTON_MENUDOWN, /**< Navigate the menus to the bottom. */ GAME_BUTTON_START, GAME_BUTTON_SELECT, GAME_BUTTON_BACK, - GAME_BUTTON_COIN, - GAME_BUTTON_OPERATOR, + GAME_BUTTON_COIN, /**< Insert a coin to play. */ + GAME_BUTTON_OPERATOR, /**< Access the operator menu. */ GAME_BUTTON_EFFECT_UP, GAME_BUTTON_EFFECT_DOWN, GAME_BUTTON_CUSTOM_01, @@ -64,18 +64,29 @@ GameButton StringToGameButton( const InputScheme* pInputs, const RString& s ); #define GAME_BUTTON_NEXT GAME_BUTTON_CUSTOM_01 // dance +/** @brief Set up the left arrow for dance mode. */ #define DANCE_BUTTON_LEFT GAME_BUTTON_CUSTOM_01 +/** @brief Set up the right arrow for dance mode. */ #define DANCE_BUTTON_RIGHT GAME_BUTTON_CUSTOM_02 +/** @brief Set up the up arrow for dance mode. */ #define DANCE_BUTTON_UP GAME_BUTTON_CUSTOM_03 +/** @brief Set up the down arrow for dance mode. */ #define DANCE_BUTTON_DOWN GAME_BUTTON_CUSTOM_04 +/** @brief Set up the upleft arrow for dance mode (solo). */ #define DANCE_BUTTON_UPLEFT GAME_BUTTON_CUSTOM_05 +/** @brief Set up the upright arrow for dance mode (solo). */ #define DANCE_BUTTON_UPRIGHT GAME_BUTTON_CUSTOM_06 #define NUM_DANCE_BUTTONS GAME_BUTTON_CUSTOM_07 // pump +/** @brief Set up the upleft arrow for pump mode. */ #define PUMP_BUTTON_UPLEFT GAME_BUTTON_CUSTOM_01 +/** @brief Set up the upright arrow for pump mode. */ #define PUMP_BUTTON_UPRIGHT GAME_BUTTON_CUSTOM_02 +/** @brief Set up the center arrow for pump mode. */ #define PUMP_BUTTON_CENTER GAME_BUTTON_CUSTOM_03 +/** @brief Set up the downleft arrow for pump mode. */ #define PUMP_BUTTON_DOWNLEFT GAME_BUTTON_CUSTOM_04 +/** @brief Set up the downright arrow for pump mode. */ #define PUMP_BUTTON_DOWNRIGHT GAME_BUTTON_CUSTOM_05 #define NUM_PUMP_BUTTONS GAME_BUTTON_CUSTOM_06 // kb7 @@ -178,7 +189,7 @@ GameButton StringToGameButton( const InputScheme* pInputs, const RString& s ); #define GAME_BUTTON_DOWN GAME_BUTTON_MENUDOWN #define GAME_BUTTON_START GAME_BUTTON_START #define GAME_BUTTON_BACK GAME_BUTTON_BACK - +/** @brief An input event specific to an InputScheme defined by a logical controller and button. */ struct GameInput { GameInput(): controller(GameController_Invalid), button(GameButton_Invalid) { } @@ -207,8 +218,10 @@ struct GameInput #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/GameplayAssist.h b/src/GameplayAssist.h index 5f153c3dc4..8a548e6b1f 100644 --- a/src/GameplayAssist.h +++ b/src/GameplayAssist.h @@ -1,5 +1,3 @@ -/** @brief GameplayAssist - Encapsulate playing of handclap and metronome. */ - #ifndef GameplayAssist_H #define GameplayAssist_H diff --git a/src/GrooveRadar.h b/src/GrooveRadar.h index 0cd6ba3d57..170d1e48d7 100644 --- a/src/GrooveRadar.h +++ b/src/GrooveRadar.h @@ -16,9 +16,16 @@ public: virtual GrooveRadar *Copy() const; virtual void LoadFromNode( const XNode* pNode ); + /** + * @brief Give the Player an empty GrooveRadar. + * @param pn the Player to give an empty GrooveRadar. */ void SetEmpty( PlayerNumber pn ); void SetFromRadarValues( PlayerNumber pn, const RadarValues &rv ); - void SetFromSteps( PlayerNumber pn, Steps* pSteps ); // NULL means no Steps + /** + * @brief Give the Player a GrooveRadar based on some Steps. + * @param pn the Player to give a GrooveRadar. + * @param pSteps the Steps to use to make the radar. If NULL, there are no Steps. */ + void SetFromSteps( PlayerNumber pn, Steps* pSteps ); // Lua void PushSelf( lua_State *L ); @@ -58,8 +65,10 @@ protected: #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/HighScore.h b/src/HighScore.h index fb99deb4c0..a0e11357f8 100644 --- a/src/HighScore.h +++ b/src/HighScore.h @@ -58,6 +58,9 @@ struct HighScore * @return true if the score would be disqualified, false otherwise. */ bool GetDisqualified() const; + /** + * @brief Set the name of the Player that earned the score. + * @param sName the name of the Player. */ void SetName( const RString &sName ); void SetGrade( Grade g ); void SetScore( int iScore ); diff --git a/src/Song.h b/src/Song.h index 7def778ee5..aefc16f763 100644 --- a/src/Song.h +++ b/src/Song.h @@ -144,7 +144,11 @@ public: /** @brief The group this Song is in. */ RString m_sGroupName; - ProfileSlot m_LoadedFromProfile; // ProfileSlot_Invalid if not loaded from a profile + /** + * @brief the Profile this came from. + * + * This is ProfileSlot_Invalid if it wasn't loaded from a profile. */ + ProfileSlot m_LoadedFromProfile; /** @brief Is the song file itself a symlink to another file? */ bool m_bIsSymLink; bool m_bEnabled; @@ -155,8 +159,11 @@ public: RString m_sSubTitle; /** @brief The artist of the Song, if it exists. */ RString m_sArtist; + /** @brief The transliterated title of the Song, if it exists. */ RString m_sMainTitleTranslit; + /** @brief The transliterated subtitle of the Song, if it exists. */ RString m_sSubTitleTranslit; + /** @brief The transliterated artist of the Song, if it exists. */ RString m_sArtistTranslit; /* If PREFSMAN->m_bShowNative is off, these are the same as GetTranslit* @@ -166,9 +173,27 @@ public: RString GetDisplayArtist() const; // Returns the transliterated titles, if any; otherwise returns the main titles. - RString GetTranslitMainTitle() const { return m_sMainTitleTranslit.size()? m_sMainTitleTranslit: m_sMainTitle; } - RString GetTranslitSubTitle() const { return m_sSubTitleTranslit.size()? m_sSubTitleTranslit: m_sSubTitle; } - RString GetTranslitArtist() const { return m_sArtistTranslit.size()? m_sArtistTranslit:m_sArtist; } + /** + * @brief Retrieve the transliterated title, or the main title if there is no translit. + * @return the proper title. */ + RString GetTranslitMainTitle() const + { + return m_sMainTitleTranslit.size()? m_sMainTitleTranslit: m_sMainTitle; + } + /** + * @brief Retrieve the transliterated subtitle, or the main subtitle if there is no translit. + * @return the proper subtitle. */ + RString GetTranslitSubTitle() const + { + return m_sSubTitleTranslit.size()? m_sSubTitleTranslit: m_sSubTitle; + } + /** + * @brief Retrieve the transliterated artist, or the main artist if there is no translit. + * @return the proper artist. */ + RString GetTranslitArtist() const + { + return m_sArtistTranslit.size()? m_sArtistTranslit:m_sArtist; + } // "title subtitle" RString GetDisplayFullTitle() const; @@ -249,9 +274,22 @@ public: typedef vector VBackgroundChange; private: - // AutoPtr instead of raw pointer so that the auto gen'd copy constructor works correctly. - AutoPtrCopyOnWrite m_BackgroundChanges[NUM_BackgroundLayer]; // these must be sorted before gameplay - AutoPtrCopyOnWrite m_ForegroundChanges; // this must be sorted before gameplay + /** + * @brief The background changes (sorted by layer) that are for this Song. + * + * This uses an AutoPtr instead of a raw pointer so that the + * auto gen'd copy constructor works correctly. + * + * This must be sorted before gameplay. */ + AutoPtrCopyOnWrite m_BackgroundChanges[NUM_BackgroundLayer]; + /** + * @brief The foreground changes that are for this Song. + * + * This uses an AutoPtr instead of a raw pointer so that the + * auto gen'd copy constructor works correctly. + * + * This must be sorted before gameplay. */ + AutoPtrCopyOnWrite m_ForegroundChanges; public: const vector &GetBackgroundChanges( BackgroundLayer bl ) const; vector &GetBackgroundChanges( BackgroundLayer bl ); @@ -277,7 +315,14 @@ public: float GetBPMAtBeat( float fBeat ) const { return m_Timing.GetBPMAtBeat( fBeat ); } void SetBPMAtBeat( float fBeat, float fBPM ) { m_Timing.SetBPMAtBeat( fBeat, fBPM ); } BPMSegment& GetBPMSegmentAtBeat( float fBeat ) { return m_Timing.GetBPMSegmentAtBeat( fBeat ); } - float GetBeatFromElapsedTime( float fElapsedTime ) const { return m_Timing.GetBeatFromElapsedTime( fElapsedTime ); } + /** + * @brief Retrieve the beat based on the specified time. + * @param fElapsedTime the amount of time since the Song started. + * @return the appropriate beat. */ + float GetBeatFromElapsedTime( float fElapsedTime ) const + { + return m_Timing.GetBeatFromElapsedTime( fElapsedTime ); + } float GetElapsedTimeFromBeat( float fBeat ) const { return m_Timing.GetElapsedTimeFromBeat( fBeat ); } bool HasSignificantBpmChangesOrStops() const; float GetStepsSeconds() const; @@ -327,7 +372,9 @@ public: void PushSelf( lua_State *L ); private: + /** @brief the Steps that belong to this Song. */ vector m_vpSteps; + /** @brief the Steps of a particular StepsType that belong to this Song. */ vector m_vpStepsByType[NUM_StepsType]; };