diff --git a/src/Course.h b/src/Course.h index e9a83ad52b..0cf8656271 100644 --- a/src/Course.h +++ b/src/Course.h @@ -33,6 +33,7 @@ enum SongSort SongSort_LowestGrades, NUM_SongSort, }; +/** @brief Loop through the various Song Sorts. */ #define FOREACH_SongSort( i ) FOREACH_ENUM( SongSort, i ) const RString& SongSortToString( SongSort ss ); const RString& SongSortToLocalizedString( SongSort ss ); diff --git a/src/Difficulty.h b/src/Difficulty.h index 8cf64671bb..63840eb1d9 100644 --- a/src/Difficulty.h +++ b/src/Difficulty.h @@ -26,6 +26,7 @@ Difficulty DwiCompatibleStringToDifficulty( const RString& sDC ); typedef Difficulty CourseDifficulty; const int NUM_CourseDifficulty = NUM_Difficulty; +/** @brief Loop through the shown course difficulties. */ #define FOREACH_ShownCourseDifficulty( cd ) for( Difficulty cd=GetNextShownCourseDifficulty((CourseDifficulty)-1); cd!=Difficulty_Invalid; cd=GetNextShownCourseDifficulty(cd) ) const RString& CourseDifficultyToLocalizedString( Difficulty dc ); diff --git a/src/EditMenu.h b/src/EditMenu.h index 0d03ef1e04..0709670202 100644 --- a/src/EditMenu.h +++ b/src/EditMenu.h @@ -23,6 +23,7 @@ enum EditMenuRow ROW_ACTION, NUM_EditMenuRow }; +/** @brief Loop through each EditMenuRow. */ #define FOREACH_EditMenuRow( r ) FOREACH_ENUM( EditMenuRow, r ) const RString& EditMenuRowToString( EditMenuRow r ); const RString& EditMenuRowToLocalizedString( EditMenuRow r ); diff --git a/src/EnumHelper.h b/src/EnumHelper.h index e7bba4e8a3..fc32a8589a 100644 --- a/src/EnumHelper.h +++ b/src/EnumHelper.h @@ -10,7 +10,9 @@ extern "C" #include "lua-5.1/src/lua.h" } +/** @brief A general foreach loop for enumerators, going up to a max value. */ #define FOREACH_ENUM_N( e, max, var ) for( e var=(e)0; var( var, +1 ) ) +/** @brief A general foreach loop for enumerators. */ #define FOREACH_ENUM( e, var ) for( e var=(e)0; var( var, +1 ) ) int CheckEnum( lua_State *L, LuaReference &table, int iPos, int iInvalid, const char *szType, bool bAllowInvalid ); @@ -126,8 +128,10 @@ namespace LuaHelpers { template<> void Push( lua_State *L, const X &Object ) #endif -/* - * (c) 2004-2006 Chris Danford, Glenn Maynard +/** + * @file + * @author Chris Danford, Glenn Maynard (c) 2004-2006 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/Foreach.h b/src/Foreach.h index f4482e12a4..93ae960c66 100644 --- a/src/Foreach.h +++ b/src/Foreach.h @@ -1,38 +1,53 @@ #ifndef Foreach_H #define Foreach_H +/** @brief General foreach loop iterating over a vector. */ #define FOREACH( elemType, vect, var ) \ for( vector::iterator var = (vect).begin(); var != (vect).end(); ++var ) +/** @brief General foreach loop iterating over a vector, using a constant iterator. */ #define FOREACH_CONST( elemType, vect, var ) \ for( vector::const_iterator var = (vect).begin(); var != (vect).end(); ++var ) +/** @brief General foreach loop iterating over a deque. */ #define FOREACHD( elemType, vect, var ) \ for( deque::iterator var = (vect).begin(); var != (vect).end(); ++var ) +/** @brief General foreach loop iterating over a deque, using a constant iterator. */ #define FOREACHD_CONST( elemType, vect, var ) \ for( deque::const_iterator var = (vect).begin(); var != (vect).end(); ++var ) +/** @brief General foreach loop iterating over a set. */ #define FOREACHS( elemType, vect, var ) \ for( set::iterator var = (vect).begin(); var != (vect).end(); ++var ) +/** @brief General foreach loop iterating over a set, using a constant iterator. */ #define FOREACHS_CONST( elemType, vect, var ) \ for( set::const_iterator var = (vect).begin(); var != (vect).end(); ++var ) +/** @brief General foreach loop iterating over a list. */ #define FOREACHL( elemType, vect, var ) \ for( list::iterator var = (vect).begin(); var != (vect).end(); ++var ) +/** @brief General foreach loop iterating over a list, using a constant iterator. */ #define FOREACHL_CONST( elemType, vect, var ) \ for( list::const_iterator var = (vect).begin(); var != (vect).end(); ++var ) +/** @brief General foreach loop iterating over a map. */ #define FOREACHM( keyType, valType, vect, var ) \ for( map::iterator var = (vect).begin(); var != (vect).end(); ++var ) +/** @brief General foreach loop iterating over a map, using a constant iterator. */ #define FOREACHM_CONST( keyType, valType, vect, var ) \ for( map::const_iterator var = (vect).begin(); var != (vect).end(); ++var ) +/** @brief General foreach loop iterating over a multimap. */ #define FOREACHMM( keyType, valType, vect, var ) \ for( multimap::iterator var = (vect).begin(); var != (vect).end(); ++var ) +/* Hmm...any reason why there is no FOREACHMM_CONST? */ + #endif -/* - * (c) 2004-2005 Chris Danford +/** + * @file + * @author Chris Danford (c) 2004-2005 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/GameConstantsAndTypes.h b/src/GameConstantsAndTypes.h index 9bd115b913..24fd0fc8f1 100644 --- a/src/GameConstantsAndTypes.h +++ b/src/GameConstantsAndTypes.h @@ -662,6 +662,7 @@ enum CourseType NUM_CourseType, CourseType_Invalid }; +/** @brief A special iterator for handling the CourseTypes. */ #define FOREACH_CourseType( i ) FOREACH_ENUM( CourseType, i ) const RString& CourseTypeToString( CourseType i ); const RString& CourseTypeToLocalizedString( CourseType i ); diff --git a/src/GameInput.h b/src/GameInput.h index 37f4a72af3..0872a04860 100644 --- a/src/GameInput.h +++ b/src/GameInput.h @@ -58,6 +58,7 @@ RString GameButtonToString( const InputScheme* pInputs, GameButton i ); RString GameButtonToLocalizedString( const InputScheme* pInputs, GameButton i ); GameButton StringToGameButton( const InputScheme* pInputs, const RString& s ); +/** @brief A special way to loop through each game button. */ #define FOREACH_GameButton_Custom( gb ) for( GameButton gb=GAME_BUTTON_CUSTOM_01; gb NUM_GRADE_TIERS_USED; #define NUM_POSSIBLE_GRADES (NUM_GRADE_TIERS_USED+1) 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) ) #endif diff --git a/src/InputMapper.h b/src/InputMapper.h index 3397f49b44..66aadc2f09 100644 --- a/src/InputMapper.h +++ b/src/InputMapper.h @@ -129,6 +129,7 @@ public: const GameButtonInfo *GetGameButtonInfo( GameButton gb ) const; const char *GetGameButtonName( GameButton gb ) const; }; +/** @brief A special foreach loop to handle the various GameButtons. */ #define FOREACH_GameButtonInScheme( s, var ) for( GameButton var=(GameButton)0; varm_iButtonsPerController; enum_add( var, +1 ) ) class InputMappings diff --git a/src/LightsManager.h b/src/LightsManager.h index 0934744ba6..6fff605686 100644 --- a/src/LightsManager.h +++ b/src/LightsManager.h @@ -23,6 +23,7 @@ enum CabinetLight NUM_CabinetLight, CabinetLight_Invalid }; +/** @brief Loop through each CabinetLight on the machine. */ #define FOREACH_CabinetLight( i ) FOREACH_ENUM( CabinetLight, i ) const RString& CabinetLightToString( CabinetLight cl ); CabinetLight StringToCabinetLight( const RString& s); diff --git a/src/LuaManager.h b/src/LuaManager.h index 83485a526e..9a644bd6f3 100644 --- a/src/LuaManager.h +++ b/src/LuaManager.h @@ -157,19 +157,21 @@ private: LuaReference *m_pOldValue; }; -/* Iterate over all elements in the table. For safety reasons, the key is pushed onto - * the stack and can be read (safely) as a string and popped or altered in any way. - * Stack management is handled automatically. That is, you need not remove all stack - * elements above the key. Once the loop exits normally, the top of the stack will be - * where it was before. If you break out of the loop early, you need to handle that - * explicitly. */ +/** + * @brief Iterate over all elements in the table. + * + * For safety reasons, the key is pushed onto the stack and can be read (safely) + * as a string and popped or altered in any way. Stack management is handled + * automatically. That is, you need not remove all stack elements above the key. + * Once the loop exits normally, the top of the stack will be where it was before. + * If you break out of the loop early, you need to handle that explicitly. */ #define FOREACH_LUATABLE(L,index) \ for( const int UNIQUE_NAME(tab) = LuaHelpers::AbsIndex(L,index), \ UNIQUE_NAME(top) = (lua_pushnil(L),lua_gettop(L)); \ lua_next(L, UNIQUE_NAME(tab)) && (lua_pushvalue(L,-2),true); \ lua_settop(L,UNIQUE_NAME(top)) ) -/* Iterate over the array elements of a table. */ +/** @brief Iterate over the array elements of a table. */ #define FOREACH_LUATABLEI(L, index, i) \ for( int UNIQUE_NAME(tab) = LuaHelpers::AbsIndex(L,index), \ UNIQUE_NAME(top) = lua_gettop(L), i = 1; \ diff --git a/src/NetworkSyncManager.h b/src/NetworkSyncManager.h index 382a753e1d..18a34455ae 100644 --- a/src/NetworkSyncManager.h +++ b/src/NetworkSyncManager.h @@ -74,6 +74,7 @@ enum NSScoreBoardColumn NUM_NSScoreBoardColumn, NSScoreBoardColumn_Invalid }; +/** @brief A special foreach loop going through each NSScoreBoardColumn. */ #define FOREACH_NSScoreBoardColumn( sc ) FOREACH_ENUM( NSScoreBoardColumn, sc ) struct NetServerInfo diff --git a/src/NoteData.h b/src/NoteData.h index 482310c4fe..af6f8bd64a 100644 --- a/src/NoteData.h +++ b/src/NoteData.h @@ -1,5 +1,3 @@ -/* NoteData - Holds data about the notes that the player is supposed to hit. */ - #ifndef NOTE_DATA_H #define NOTE_DATA_H @@ -8,17 +6,24 @@ #include #include +/** @brief Act on each non empty row in the specific track. */ #define FOREACH_NONEMPTY_ROW_IN_TRACK( nd, track, row ) \ for( int row = -1; (nd).GetNextTapNoteRowForTrack(track,row); ) +/** @brief Act on each non empty row in the specified track within the specified range. */ #define FOREACH_NONEMPTY_ROW_IN_TRACK_RANGE( nd, track, row, start, last ) \ for( int row = start-1; (nd).GetNextTapNoteRowForTrack(track,row) && row < (last); ) +/** @brief Act on each non empty row in the specified track within the specified range, + going in reverse order. */ #define FOREACH_NONEMPTY_ROW_IN_TRACK_RANGE_REVERSE( nd, track, row, start, last ) \ for( int row = last; (nd).GetPrevTapNoteRowForTrack(track,row) && row >= (start); ) +/** @brief Act on each non empty row for all of the tracks. */ #define FOREACH_NONEMPTY_ROW_ALL_TRACKS( nd, row ) \ for( int row = -1; (nd).GetNextTapNoteRowForAllTracks(row); ) +/** @brief Act on each non empty row for all of the tracks within the specified range. */ #define FOREACH_NONEMPTY_ROW_ALL_TRACKS_RANGE( nd, row, start, last ) \ for( int row = start-1; (nd).GetNextTapNoteRowForAllTracks(row) && row < (last); ) +/** @brief Holds data about the notes that the player is supposed to hit. */ class NoteData { public: diff --git a/src/NoteDisplay.cpp b/src/NoteDisplay.cpp index 238bdf84f0..25f224f9c8 100644 --- a/src/NoteDisplay.cpp +++ b/src/NoteDisplay.cpp @@ -15,6 +15,7 @@ #include "RageMath.h" const RString& NoteNotePartToString( NotePart i ); +/** @brief A foreach loop going through the different NoteParts. */ #define FOREACH_NotePart( i ) FOREACH_ENUM( NotePart, i ) static const char *NotePartNames[] = { diff --git a/src/NoteDisplay.h b/src/NoteDisplay.h index 1e9def75b4..8690ae13a6 100644 --- a/src/NoteDisplay.h +++ b/src/NoteDisplay.h @@ -56,6 +56,7 @@ enum HoldType NUM_HoldType, HoldType_Invalid }; +/** @brief Loop through each HoldType. */ #define FOREACH_HoldType( i ) FOREACH_ENUM( HoldType, i ) const RString &HoldTypeToString( HoldType ht ); @@ -66,6 +67,7 @@ enum ActiveType NUM_ActiveType, ActiveType_Invalid }; +/** @brief Loop through each ActiveType. */ #define FOREACH_ActiveType( i ) FOREACH_ENUM( ActiveType, i ) const RString &ActiveTypeToString( ActiveType at ); diff --git a/src/PlayerNumber.h b/src/PlayerNumber.h index 11bd42a8b1..109deea091 100644 --- a/src/PlayerNumber.h +++ b/src/PlayerNumber.h @@ -19,7 +19,7 @@ const PlayerNumber PLAYER_INVALID = PlayerNumber_Invalid; const RString& PlayerNumberToString( PlayerNumber pn ); const RString& PlayerNumberToLocalizedString( PlayerNumber pn ); LuaDeclareType( PlayerNumber ); - +/** @brief A foreach loop to handle the different players. */ #define FOREACH_PlayerNumber( pn ) FOREACH_ENUM( PlayerNumber, pn ) const PlayerNumber OPPOSITE_PLAYER[NUM_PLAYERS] = { PLAYER_2, PLAYER_1 }; @@ -65,7 +65,7 @@ enum MultiPlayer const RString& MultiPlayerToString( MultiPlayer mp ); const RString& MultiPlayerToLocalizedString( MultiPlayer mp ); LuaDeclareType( MultiPlayer ); - +/** @brief A foreach loop to handle the different Players in MultiPlayer. */ #define FOREACH_MultiPlayer( pn ) FOREACH_ENUM( MultiPlayer, pn ) #endif diff --git a/src/RageInputDevice.h b/src/RageInputDevice.h index 51e41a0c0d..d27e76134b 100644 --- a/src/RageInputDevice.h +++ b/src/RageInputDevice.h @@ -48,8 +48,9 @@ enum InputDevice DEVICE_MIDI, DEVICE_MOUSE, NUM_InputDevice, // leave this at the end - InputDevice_Invalid // means this is NULL + InputDevice_Invalid // means this is NULL }; +/** @brief A special foreach loop for each input device. */ #define FOREACH_InputDevice( i ) FOREACH_ENUM( InputDevice, i ) const RString& InputDeviceToString( InputDevice i ); InputDevice StringToInputDevice( const RString& s ); diff --git a/src/ScreenEdit.h b/src/ScreenEdit.h index 7587b98dcc..1fe452b6d6 100644 --- a/src/ScreenEdit.h +++ b/src/ScreenEdit.h @@ -136,6 +136,7 @@ enum EditButton NUM_EditButton, // leave this at the end EditButton_Invalid }; +/** @brief A special foreach loop for the different edit buttons. */ #define FOREACH_EditButton( e ) FOREACH_ENUM( EditButton, e ) const int NUM_EDIT_TO_DEVICE_SLOTS = 2; const int NUM_EDIT_TO_MENU_SLOTS = 2; diff --git a/src/ScreenGameplay.h b/src/ScreenGameplay.h index 0ee6a7d5f3..80d2af4b3b 100644 --- a/src/ScreenGameplay.h +++ b/src/ScreenGameplay.h @@ -296,10 +296,15 @@ vector::iterator GetNextEnabledPlayerNumberInfo ( vector vector::iterator GetNextPlayerNumberInfo ( vector::iterator iter, vector &v ); vector::iterator GetNextVisiblePlayerInfo ( vector::iterator iter, vector &v ); +/** @brief Get each enabled Player's info. */ #define FOREACH_EnabledPlayerInfo( v, pi ) for( vector::iterator pi = GetNextEnabledPlayerInfo (v.begin(),v); pi != v.end(); pi = GetNextEnabledPlayerInfo(++pi,v) ) +/** @brief Get each enabled Player's info as long as it's not a dummy player. */ #define FOREACH_EnabledPlayerInfoNotDummy( v, pi ) for( vector::iterator pi = GetNextEnabledPlayerInfoNotDummy (v.begin(),v); pi != v.end(); pi = GetNextEnabledPlayerInfoNotDummy(++pi,v) ) +/** @brief Get each enabled Player Number's info. */ #define FOREACH_EnabledPlayerNumberInfo( v, pi ) for( vector::iterator pi = GetNextEnabledPlayerNumberInfo (v.begin(),v); pi != v.end(); pi = GetNextEnabledPlayerNumberInfo(++pi,v) ) +/** @brief Get each Player Number's info, regardless of whether it's enabled or not. */ #define FOREACH_PlayerNumberInfo( v, pi ) for( vector::iterator pi = GetNextPlayerNumberInfo (v.begin(),v); pi != v.end(); pi = GetNextPlayerNumberInfo(++pi,v) ) +/** @brief Get each visible Player's info. */ #define FOREACH_VisiblePlayerInfo( v, pi ) for( vector::iterator pi = GetNextVisiblePlayerInfo (v.begin(),v); pi != v.end(); pi = GetNextVisiblePlayerInfo(++pi,v) ) diff --git a/src/ScreenOptionsManageEditSteps.cpp b/src/ScreenOptionsManageEditSteps.cpp index ee5d23807c..7fc0b1f7de 100644 --- a/src/ScreenOptionsManageEditSteps.cpp +++ b/src/ScreenOptionsManageEditSteps.cpp @@ -37,6 +37,7 @@ static const char *StepsEditActionNames[] = { "Delete", }; XToString( StepsEditAction ); +/** @brief Loop through each StepsEditAction. */ #define FOREACH_StepsEditAction( i ) FOREACH_ENUM( StepsEditAction, i ) static MenuDef g_TempMenu( diff --git a/src/ScreenOptionsManageProfiles.cpp b/src/ScreenOptionsManageProfiles.cpp index 7c75399601..272dd2d478 100644 --- a/src/ScreenOptionsManageProfiles.cpp +++ b/src/ScreenOptionsManageProfiles.cpp @@ -42,6 +42,7 @@ static const char *ProfileActionNames[] = { }; XToString( ProfileAction ); XToLocalizedString( ProfileAction ); +/** @brief Loop through each ProfileAction. */ #define FOREACH_ProfileAction( i ) FOREACH_ENUM( ProfileAction, i ) static MenuDef g_TempMenu( diff --git a/src/ScreenSelectMaster.h b/src/ScreenSelectMaster.h index b2f1e30cd1..b86679feff 100644 --- a/src/ScreenSelectMaster.h +++ b/src/ScreenSelectMaster.h @@ -16,6 +16,7 @@ enum MenuDir MenuDir_Auto, // when players join and the selection becomes invalid NUM_MenuDir, }; +/** @brief A special foreach loop through the different menu directions. */ #define FOREACH_MenuDir( md ) FOREACH_ENUM( MenuDir, md ) const RString& MenuDirToString( MenuDir md ); diff --git a/src/ScreenSetTime.cpp b/src/ScreenSetTime.cpp index 72eaea7a82..1860a316b5 100644 --- a/src/ScreenSetTime.cpp +++ b/src/ScreenSetTime.cpp @@ -18,6 +18,7 @@ static const char *SetTimeSelectionNames[] = { "Second", }; XToString( SetTimeSelection ); +/** @brief A foreach iterator through the time selections. */ #define FOREACH_SetTimeSelection( s ) FOREACH_ENUM( SetTimeSelection, s ) const float g_X[NUM_SetTimeSelection] = diff --git a/src/ScreenTextEntry.h b/src/ScreenTextEntry.h index 04d2b0ffe0..0bebcee94d 100644 --- a/src/ScreenTextEntry.h +++ b/src/ScreenTextEntry.h @@ -1,5 +1,3 @@ -/* ScreenTextEntry - Displays a text entry box over the top of another screen. */ - #ifndef SCREEN_TEXT_ENTRY_H #define SCREEN_TEXT_ENTRY_H @@ -9,20 +7,34 @@ #include "ThemeMetric.h" #include "InputEventPlus.h" +/** @brief The list of possible keyboard rows. */ enum KeyboardRow { - R1, R2, R3, R4, R5, R6, R7, + R1, + R2, + R3, + R4, + R5, + R6, + R7, KEYBOARD_ROW_SPECIAL, NUM_KeyboardRow, KeyboardRow_Invalid }; +/** @brief A special foreach loop for the KeyboardRow enum. */ #define FOREACH_KeyboardRow( i ) FOREACH_ENUM( KeyboardRow, i ) +/** @brief The maximum number of keys per row. */ const int KEYS_PER_ROW = 13; +/** @brief The list of very special keys inside some rows. */ enum KeyboardRowSpecialKey { - SPACEBAR=2, BACKSPACE=5, CANCEL=8, DONE=11 + SPACEBAR=2, /**< The space bar key. */ + BACKSPACE=5, /**< The backspace key. */ + CANCEL=8, + DONE=11 }; +/** @brief Displays a text entry box over the top of another screen. */ class ScreenTextEntry : public ScreenWithMenuElements { public: @@ -64,7 +76,10 @@ public: RString sQuestion; RString sInitialAnswer; int iMaxInputLength; - bool bPassword; // (optional) + /** @brief Is there a password involved with this setting? + * + * This parameter doesn't have to be used. */ + bool bPassword; LuaReference Validate; // (RString sAnswer, RString sErrorOut; optional) LuaReference OnOK; // (RString sAnswer; optional) LuaReference OnCancel; // (optional) diff --git a/src/ThemeManager.h b/src/ThemeManager.h index f4e9212a16..7a78b777af 100644 --- a/src/ThemeManager.h +++ b/src/ThemeManager.h @@ -21,6 +21,7 @@ enum ElementCategory NUM_ElementCategory, ElementCategory_Invalid }; +/** @brief A special foreach loop going through each ElementCategory. */ #define FOREACH_ElementCategory( ec ) FOREACH_ENUM( ElementCategory, ec ) const RString& ElementCategoryToString( ElementCategory ec ); ElementCategory StringToElementCategory( const RString& s ); diff --git a/src/XmlFile.h b/src/XmlFile.h index 2c81898b76..3afeb82873 100644 --- a/src/XmlFile.h +++ b/src/XmlFile.h @@ -55,24 +55,24 @@ public: typedef map XAttrs; class XNode; typedef vector XNodes; - +/** @brief Loop through each node. */ #define FOREACH_Attr( pNode, Var ) \ for( XAttrs::iterator Var = (pNode)->m_attrs.begin(); \ Var != (pNode)->m_attrs.end(); \ ++Var ) - +/** @brief Loop through each node, using a constant iterator. */ #define FOREACH_CONST_Attr( pNode, Var ) \ for( XAttrs::const_iterator Var = (pNode)->m_attrs.begin(); \ Var != (pNode)->m_attrs.end(); \ ++Var ) - +/** @brief Loop through each child. */ #define FOREACH_Child( pNode, Var ) \ XNode *Var = NULL; \ for( XNodes::iterator Var##Iter = (pNode)->m_childs.begin(); \ Var = (Var##Iter != (pNode)->m_childs.end())? *Var##Iter:NULL, \ Var##Iter != (pNode)->m_childs.end(); \ ++Var##Iter ) - +/** @brief Loop through each child, using a constant iterator. */ #define FOREACH_CONST_Child( pNode, Var ) \ const XNode *Var = NULL; \ for( XNodes::const_iterator Var##Iter = (pNode)->m_childs.begin(); \