From e3e6eae012ca711c2504b977bf572bfe2a47e48f Mon Sep 17 00:00:00 2001 From: Jason Felds Date: Fri, 18 Feb 2011 20:35:49 -0500 Subject: [PATCH] More doxygen. Start of AutoScreenMessage( * ); The lack of semicolon messes up the doc generator. --- src/Screen.h | 52 ++++++++++++++++++++++++++++++-------------- src/ScreenGameplay.h | 47 ++++++++++++++++++++++++++++++++------- 2 files changed, 75 insertions(+), 24 deletions(-) diff --git a/src/Screen.h b/src/Screen.h index 837d4114c5..e230958714 100644 --- a/src/Screen.h +++ b/src/Screen.h @@ -1,5 +1,3 @@ -/* Screen - Class that holds a screen-full of Actors. */ - #ifndef SCREEN_H #define SCREEN_H @@ -22,18 +20,20 @@ struct RegisterScreenClass { RegisterScreenClass( const RString &sClassName, Cre static Screen* Create##className( const RString &sName ) { LuaThreadVariable var( "LoadingScreen", sName ); Screen *pRet = new className; pRet->SetName( sName ); Screen::InitScreen( pRet ); return pRet; } \ static RegisterScreenClass register_##className( #className, Create##className ) +/** @brief The different types of screens available. */ enum ScreenType { - attract, - game_menu, - gameplay, - system_menu, - NUM_ScreenType, + attract, /**< The attract/demo mode, inviting players to play. */ + game_menu, /**< The menu screens, where options can be set before playing. */ + gameplay, /**< The gameplay screen, where the actual game takes place. */ + system_menu, /**< The system/operator menu, where special options are set. */ + NUM_ScreenType, /**< The number of screen types. */ ScreenType_Invalid }; const RString& ScreenTypeToString( ScreenType st ); LuaDeclareType( ScreenType ); +/** @brief Class that holds a screen-full of Actors. */ class Screen : public ActorFrame { public: @@ -41,14 +41,17 @@ public: virtual ~Screen(); - /* This is called immediately after construction, to allow initializing after all - * derived classes exist. (Don't call it directly; use InitScreen.) */ + /** + * @brief This is called immediately after construction, + * to allow initializing after all derived classes exist. + * + * Don't call it directly; use InitScreen instead. */ virtual void Init(); - // This is called immediately before the screen is used. + /** @brief This is called immediately before the screen is used. */ virtual void BeginScreen(); - // This is called when the screen is popped. + /** @brief This is called when the screen is popped. */ virtual void EndScreen(); virtual void Update( float fDeltaTime ); @@ -58,34 +61,49 @@ public: void SetLockInputSecs( float f ) { m_fLockInputSecs = f; } void PostScreenMessage( const ScreenMessage SM, float fDelay ); + /** @brief Clear the entire message queue. */ void ClearMessageQueue(); - void ClearMessageQueue( const ScreenMessage SM ); // clear of a specific SM + /** + * @brief Clear the message queue of a specific ScreenMessage. + * @param SM the specific ScreenMessage to get out of the Queue. */ + void ClearMessageQueue( const ScreenMessage SM ); virtual ScreenType GetScreenType() const { return ALLOW_OPERATOR_MENU_BUTTON ? game_menu : system_menu; } bool AllowOperatorMenuButton() const { return ALLOW_OPERATOR_MENU_BUTTON; } + /** + * @brief Determine if we allow extra players to join in on this screen. + * @return false, for players should never be able to join while in progress. */ virtual bool AllowLateJoin() const { return false; } // Lua virtual void PushSelf( lua_State *L ); protected: - // structure for holding messages sent to a Screen + /** @brief Holds the messages sent to a Screen. */ struct QueuedScreenMessage { + /** @brief The message being held. */ ScreenMessage SM; + /** @brief How long the message is up. */ float fDelayRemaining; }; + /** @brief The list of messages that are sent to a Screen. */ vector m_QueuedMessages; static bool SortMessagesByDelayRemaining(const QueuedScreenMessage &m1, const QueuedScreenMessage &m2); InputQueueCodeSet m_Codes; + /** @brief Do we allow the operator menu button to be pressed here? */ ThemeMetric ALLOW_OPERATOR_MENU_BUTTON; + /** @brief Do we handle the back button being pressed here? */ ThemeMetric HANDLE_BACK_BUTTON; ThemeMetric REPEAT_RATE; ThemeMetric REPEAT_DELAY; ThemeMetric LIGHTS_MODE; - // If left blank, the NextScreen metric will be used. + /** + * @brief The next screen to go to once this screen is done. + * + * If this is blank, the NextScreen metric will be used. */ RString m_sNextScreen; RString m_sPrevScreen; ScreenMessage m_smSendOnPop; @@ -112,8 +130,10 @@ public: #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/ScreenGameplay.h b/src/ScreenGameplay.h index 895f537000..0ee6a7d5f3 100644 --- a/src/ScreenGameplay.h +++ b/src/ScreenGameplay.h @@ -1,5 +1,3 @@ -/** @brief ScreenGameplay - The music plays, the notes scroll, and the Player is pressing buttons. */ - #ifndef SCREEN_GAMEPLAY_H #define SCREEN_GAMEPLAY_H @@ -33,9 +31,9 @@ class ScoreKeeper; class Background; class Foreground; -AutoScreenMessage( SM_NotesEnded ) -AutoScreenMessage( SM_BeginFailed ) -AutoScreenMessage( SM_LeaveGameplay ) +AutoScreenMessage( SM_NotesEnded ); +AutoScreenMessage( SM_BeginFailed ); +AutoScreenMessage( SM_LeaveGameplay ); class PlayerInfo { @@ -48,6 +46,10 @@ public: /** @brief The player has lost all of their lives: show the special game over. */ void ShowOniGameOver(); + /** + * @brief Retrieve the player's state and stage stats index. + * @return the player's state and stage stats index. + */ MultiPlayer GetPlayerStateAndStageStatsIndex() { return m_pn == PLAYER_INVALID ? m_mp : (MultiPlayer)m_pn; } PlayerState *GetPlayerState(); PlayerStageStats *GetPlayerStageStats(); @@ -56,6 +58,9 @@ public: * @brief Determine if the player information is enabled. * @return its success or failure. */ bool IsEnabled(); + /** + * @brief Determine if we're in MultiPlayer. + * @return true if it is MultiPlayer, false otherwise. */ bool IsMultiPlayer() const { return m_mp != MultiPlayer_Invalid; } RString GetName() const { @@ -70,6 +75,7 @@ public: // Lua void PushSelf( lua_State *L ); + /** @brief The present Player that is playing the game. */ PlayerNumber m_pn; MultiPlayer m_mp; bool m_bIsDummy; @@ -80,20 +86,38 @@ public: PlayerStageStats m_PlayerStageStatsDummy; SoundEffectControl m_SoundEffectControl; - vector m_vpStepsQueue; // size may be >1 if playing a course - vector m_asModifiersQueue;// size may be >1 if playing a course + /** + * @brief The list of Steps a player has to go through in this set. + * + * The size may be greater than 1 if playing a course. */ + vector m_vpStepsQueue; + /** + * @brief The list of attack modifiers a player has to go through in this set. + * + * The size may be greater than 1 if playing a course. */ + vector m_asModifiersQueue; + /** @brief The LifeMeter showing a Player's health. */ LifeMeter *m_pLifeMeter; + /** @brief The current Song number in a Course. */ BitmapText *m_ptextCourseSongNumber; + /** @brief The description of the current Steps. */ BitmapText *m_ptextStepsDescription; + /** @brief The display for the primary ScoreKeeper. */ ScoreDisplay *m_pPrimaryScoreDisplay; + /** @brief The display for the secondary ScoreKeeper. */ ScoreDisplay *m_pSecondaryScoreDisplay; + /** @brief The primary ScoreKeeper for keeping track of the score. */ ScoreKeeper *m_pPrimaryScoreKeeper; + /** @brief The secondary ScoreKeeper for keeping track of the score. */ ScoreKeeper *m_pSecondaryScoreKeeper; + /** @brief The current PlayerOptions that are activated. */ BitmapText *m_ptextPlayerOptions; + /** @brief The current attack modifiers that are in play for the moment. */ ActiveAttackList *m_pActiveAttackList; + /** @brief The NoteData the Player has to get through. */ NoteData m_NoteData; Player *m_pPlayer; @@ -103,11 +127,12 @@ public: * This is mainly used in PLAY_MODE_BATTLE. */ Inventory *m_pInventory; - StepsDisplay *m_pStepsDisplay; + StepsDisplay *m_pStepsDisplay; AutoActor m_sprOniGameOver; }; +/** @brief The music plays, the notes scroll, and the Player is pressing buttons. */ class ScreenGameplay : public ScreenWithMenuElements { public: @@ -122,8 +147,14 @@ public: virtual void HandleMessage( const Message &msg ); virtual void Cancel( ScreenMessage smSendWhenDone ); + /** + * @brief Retrieve the current ScreenType. + * @return the gameplay ScreenType. */ virtual ScreenType GetScreenType() const { return gameplay; } + /** + * @brief Determine if we are to center the columns for just one player. + * @return true if we center the solo player, false otherwise. */ bool Center1Player() const; // Lua