diff --git a/src/CourseUtil.h b/src/CourseUtil.h index 80bf355c6f..d0c4738cef 100644 --- a/src/CourseUtil.h +++ b/src/CourseUtil.h @@ -1,4 +1,4 @@ -/* CourseUtil - Utility functions that deal with Course. */ +/** @brief CourseUtil - Utility functions that deal with Course. */ #ifndef COURSEUTIL_H #define COURSEUTIL_H @@ -93,8 +93,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/GameManager.h b/src/GameManager.h index 9f6bf091e9..666700bb62 100644 --- a/src/GameManager.h +++ b/src/GameManager.h @@ -1,4 +1,4 @@ -/* GameManager - Manages Games and Styles. */ +/** @brief GameManager - Manages Games and Styles. */ #ifndef GAMEMANAGER_H #define GAMEMANAGER_H @@ -10,12 +10,16 @@ struct lua_State; #include "GameConstantsAndTypes.h" #include "GameInput.h" +/** @brief The collective information about a Steps' Type. */ struct StepsTypeInfo { const char *szName; + /** @brief The number of tracks, or columns, of this type. */ int iNumTracks; - bool bAllowAutogen; // allow this type to be autogen'd to other types - StepsTypeCategory m_StepsTypeCategory; // what is the most basic StyleType this is used with? + /** @brief A flag to determine if we allow this type to be autogen'ed to other types. */ + bool bAllowAutogen; + /** @brief The most basic StyleType that this StpesTypeInfo is used with. */ + StepsTypeCategory m_StepsTypeCategory; RString GetLocalizedString() const; }; @@ -55,8 +59,10 @@ extern GameManager* GAMEMAN; // global and accessable from anywhere in our progr #endif -/* - * (c) 2001-2004 Chris Danford, Glenn Maynard +/** + * @file + * @author Chris Danford, Glenn Maynard (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/Grade.h b/src/Grade.h index 34d6dc2286..c520f39c6c 100644 --- a/src/Grade.h +++ b/src/Grade.h @@ -1,4 +1,4 @@ -/* Grade - Mark the player receives after clearing a song. */ +/** @brief Grade - Mark the player receives after clearing a song. */ #ifndef GRADE_H #define GRADE_H @@ -7,16 +7,21 @@ #include "EnumHelper.h" #include "ThemeMetric.h" +/** + * @brief Have a specific number of passing grade tiers. + * + * TODO: Look into flexible grading tiers. */ #define NUM_Grade_TierS 20 +/** @brief The list of grading tiers available. */ enum Grade { - Grade_Tier01, // = AAAA - Grade_Tier02, // = AAA - Grade_Tier03, // = AA - Grade_Tier04, // = A - Grade_Tier05, // = B - Grade_Tier06, // = C - Grade_Tier07, // = D + Grade_Tier01, /**< Usually an AAAA */ + Grade_Tier02, /**< Usually an AAA */ + Grade_Tier03, /**< Usually an AA */ + Grade_Tier04, /**< Usually an A */ + Grade_Tier05, /**< Usually a B */ + Grade_Tier06, /**< Usually a C */ + Grade_Tier07, /**< Usually a D */ Grade_Tier08, Grade_Tier09, Grade_Tier10, @@ -30,14 +35,20 @@ enum Grade Grade_Tier18, Grade_Tier19, Grade_Tier20, - Grade_Failed, // = E + Grade_Failed, /**< Usually an E */ NUM_Grade, Grade_Invalid, }; #define Grade_NoData Grade_Invalid -/* This is in the header so the test sets don't require Grade.cpp (through PrefsManager), - * since that pulls in ThemeManager. */ +/** + * @brief Convert the grade supplied to a string representation. + * + * This is in the header so the test sets don't require Grade.cpp (through PrefsManager), + * since that pulls in ThemeManager. + * @param g the grade to convert. + * @return the string reprsentation. + */ static inline RString GradeToString( Grade g ) { ASSERT_M( (g >= 0 && g= TNS_W5). */ + /** + * @brief Offset, in seconds, for a tap grade. + * + * Negative numbers mean the note was hit early; positive numbers mean + * it was hit late. These values are only meaningful for graded taps + * (tns >= TNS_W5). */ float fTapNoteOffset; - // If the whole row has been judged, all taps on the row will be set to hidden. + /** @brief If the whole row has been judged, all taps on the row will be set to hidden. */ bool bHidden; // XML XNode* CreateNode() const; void LoadFromNode( const XNode* pNode ); }; - +/** @brief The result of holding (or letting go of) a hold note. */ struct HoldNoteResult { HoldNoteResult() : hns(HNS_None), fLife(1.f), fOverlappedTime(0), iLastHeldRow(0), iCheckpointsHit(0), iCheckpointsMissed(0), bHeld(false), bActive(false) { } @@ -34,46 +39,58 @@ struct HoldNoteResult HoldNoteScore hns; - /* 1.0 means this HoldNote has full life. - * 0.0 means this HoldNote is dead + /** + * @brief the current life of the hold. + * + * 1.0 means this HoldNote has full life. + * + * 0.0 means this HoldNote is dead. + * * When this value hits 0.0 for the first time, m_HoldScore becomes HNS_LetGo. * If the life is > 0.0 when the HoldNote ends, then m_HoldScore becomes HNS_Held. */ float fLife; - /* The number of seconds the hold note has overlapped the current beat, or 0 - * if it doesn't overlap. */ + /** @brief The number of seconds the hold note has overlapped the current beat. + * + * This value is 0 if it doesn't overlap. */ float fOverlappedTime; - /* Last index where fLife was greater than 0. If the tap was missed, this + /** @brief Last index where fLife was greater than 0. If the tap was missed, this * will be the first index of the hold. */ int iLastHeldRow; - // If checkpoint holds are enabled, the number of checkpoints hit and missed. + /** @brief If checkpoint holds are enabled, the number of checkpoints hit. */ int iCheckpointsHit; + /** @brief If checkpoint holds are enabled, the number of checkpoints missed. */ int iCheckpointsMissed; - bool bHeld; // Was button held during last update? - bool bActive; // Is life > 0 && overlaps current beat + /** @brief Was the button held during the last update? */ + bool bHeld; + /** @brief Is there life in the hold and does it overlap the current beat? */ + bool bActive; // XML XNode* CreateNode() const; void LoadFromNode( const XNode* pNode ); }; +/** @brief The various properties of a tap note. */ struct TapNote { + /** @brief What is the TapNote's core type? */ enum Type { - empty, // no note here - tap, // step on this - hold_head, // graded like a tap - hold_tail, // in 2sand3s mode, holds are deleted and hold_tail is added - mine, // don't step! - lift, // up - attack, - autoKeysound, - fake, // not scored for or against + empty, /**< There is no note here. */ + tap, /**< The player simply steps on this. */ + hold_head, /**< This is graded like the Tap type, but should be held. */ + hold_tail, /**< In 2sand3s mode, holds are deleted and hold_tail is added. */ + mine, /**< In most modes, it is suggested to not step on these mines. */ + lift, /**< Lift your foot up when it crosses the target area. */ + attack, /**< Hitting this note causes an attack to take place. */ + autoKeysound, /**< A special sound is played when this note crosses the target area. */ + fake, /**< This arrow can't be scored for or against the player. */ }; + /** @brief The list of a TapNote's sub types. */ enum SubType { hold_head_hold, @@ -82,18 +99,24 @@ struct TapNote NUM_SubType, SubType_Invalid }; + /** @brief The different places a TapNote could come from. */ enum Source { - original, // part of the original NoteData - addition, // additional note added by a transform + original, /**< This note is part of the original NoteData. */ + addition, /**< This note is additional note added by a transform. */ }; - + /** @brief The core note type that is about to cross the target area. */ Type type; - SubType subType; // Only used if type is hold_head. + /** @brief The sub type of the note. This is only used if the type is hold_head. */ + SubType subType; + /** @brief The originating source of the TapNote. */ Source source; + /** @brief The result of hitting or missing the TapNote. */ TapNoteResult result; - PlayerNumber pn; // used in routine mode - bool bHopoPossible; // set just before gameplay begins + /** @brief The Player that is supposed to hit this note. This is mainly for Routine Mode. */ + PlayerNumber pn; + /** @brief Can this note be hammered on or pulled off? This is set before gameplay begins. */ + bool bHopoPossible; // used only if Type == attack: RString sAttackModifiers; @@ -173,30 +196,42 @@ extern TapNote TAP_ORIGINAL_FAKE; // 'F' extern TapNote TAP_ADDITION_TAP; extern TapNote TAP_ADDITION_MINE; -// TODO: Don't have a hard-coded track limit. +/** + * @brief The number of tracks allowed. + * + * TODO: Don't have a hard-coded track limit. + */ const int MAX_NOTE_TRACKS = 16; -/* This is a divisor for our "fixed-point" time/beat representation. It must be +/** + * @brief The number of rows per beat. + * + * This is a divisor for our "fixed-point" time/beat representation. It must be * evenly divisible by 2, 3, and 4, to exactly represent 8th, 12th and 16th notes. */ const int ROWS_PER_BEAT = 48; -// In the editor, enforce a reasonable limit on the number of notes. +/** + * @brief Enforce a maximum number of notes per measure in the step editor. + * + * TODO: See if there is a way to de-hard-code this number. + */ const int MAX_NOTES_PER_MEASURE = 50; - +/** @brief The max number of rows allowed for a Steps pattern. */ const int MAX_NOTE_ROW = (1<<30); +/** @brief The list of quantized note types allowed at present. */ enum NoteType { - NOTE_TYPE_4TH, // quarter note - NOTE_TYPE_8TH, // eighth note - NOTE_TYPE_12TH, // quarter note triplet - NOTE_TYPE_16TH, // sixteenth note - NOTE_TYPE_24TH, // eighth note triplet - NOTE_TYPE_32ND, // thirty-second note - NOTE_TYPE_48TH, // sixteenth note triplet - NOTE_TYPE_64TH, // sixty-fourth note - NOTE_TYPE_192ND,// sixty-fourth note triplet + NOTE_TYPE_4TH, /**< quarter note */ + NOTE_TYPE_8TH, /**< eighth note */ + NOTE_TYPE_12TH, /**< quarter note triplet */ + NOTE_TYPE_16TH, /**< sixteenth note */ + NOTE_TYPE_24TH, /**< eighth note triplet */ + NOTE_TYPE_32ND, /**< thirty-second note */ + NOTE_TYPE_48TH, /**< sixteenth note triplet */ + NOTE_TYPE_64TH, /**< sixty-fourth note */ + NOTE_TYPE_192ND,/**< sixty-fourth note triplet */ NUM_NoteType, NoteType_Invalid }; @@ -225,8 +260,10 @@ inline float NoteRowToBeat( int iRow ) { return iRow / (float)ROWS_PER_BEAT; } #endif -/* - * (c) 2001-2004 Chris Danford, Glenn Maynard +/** + * @file + * @author Chris Danford, Glenn Maynard (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/ProductInfo.h b/src/ProductInfo.h index 81cb2b2764..f64d44756e 100644 --- a/src/ProductInfo.h +++ b/src/ProductInfo.h @@ -1,30 +1,48 @@ -/* ProductInfo - Branding strings. Don't forget to also change ProductInfo.inc! */ +/** @brief ProductInfo - Branding strings. Don't forget to also change ProductInfo.inc! */ #ifndef PRODUCT_INFO_H #define PRODUCT_INFO_H -// A friendly string to refer to the product in crash dialogs, etc - i.e. "StepMania" not "StepMania4" +/** + * @brief A friendly string to refer to the product in crash dialogs, etc. + * + * As an example, use "StepMania" here, not "StepMania4". + */ #define PRODUCT_FAMILY_BARE sm-ssc -// A unique name for each application that you might want installed side-by-side with other applications - i.e. "StepMania4" not "StepMania" (would conflict with StepMania 3.x) +/** + * @brief A unique name for each application that you might want installed side-by-side with other applications. + * + * As an example, use "StepMania4" here, not "StepMania". + * It would cause a conflict with older versions such as StepMania 3.X. + */ #define PRODUCT_ID_BARE sm-ssc -/* Version info displayed to the user. +/** + * @brief Version info displayed to the user. + * * These are the 'official' version designations: + * + */ #ifndef PRODUCT_VER_BARE #define PRODUCT_VER_BARE v1.2.1 #endif -// A unique ID for a build of an application. This is used in crash reports and in the network code's version handling +/** + * @brief A unique ID for a build of an application. + * + * This is used in crash reports and in the network code's version handling. + */ #define PRODUCT_ID_VER_BARE PRODUCT_ID_BARE PRODUCT_VER_BARE // These cannot be #undef'd so make them unlikely to conflict with anything @@ -37,14 +55,17 @@ #define PRODUCT_ID_VER PRODUCT_XSTRINGIFY(PRODUCT_ID_VER_BARE) #define VIDEO_TROUBLESHOOTING_URL "http://www.stepmania.com/stepmania/mediawiki.php?title=Video_Driver_Troubleshooting" +/** @brief The URL to report bugs on the program. */ #define REPORT_BUG_URL "http://ssc.ajworld.net/sm-ssc/bugtracker/" #define CAN_INSTALL_PACKAGES true #endif -/* - * (c) 2003-2005 Chris Danford +/** + * @file + * @author Chris Danford (c) 2003-2005 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/RadarValues.h b/src/RadarValues.h index c738129fc7..0d217102d3 100644 --- a/src/RadarValues.h +++ b/src/RadarValues.h @@ -1,4 +1,4 @@ -/* RadarValues - Cached song statistics. */ +/** @brief RadarValues - Cached song statistics. */ #ifndef RARAR_VALUES_H #define RARAR_VALUES_H @@ -6,11 +6,12 @@ #include "GameConstantsAndTypes.h" #include "ThemeMetric.h" +/** @brief Unknown radar values are given a default value. */ #define RADAR_VAL_UNKNOWN -1 class XNode; struct lua_State; - +/** @brief The collection of radar values. */ struct RadarValues { union Values @@ -40,12 +41,22 @@ struct RadarValues void MakeUnknown(); void Zero(); + /** + * @brief Add one set of radar values to another. + * @param other The other set of radar values to add. + * @return the new set of radar values. + */ RadarValues& operator+=( const RadarValues& other ) { FOREACH_ENUM( RadarCategory, rc ) m_Values.f[rc] += other.m_Values.f[rc]; return *this; } + /** + * @brief Determine if one set of radar values are equal to another. + * @param other The otehr set of radar values. + * @return true if the two sets are equal, false otherwise. + */ bool operator==( const RadarValues& other ) const { FOREACH_ENUM( RadarCategory, rc ) @@ -55,6 +66,11 @@ struct RadarValues } return true; } + /** + * @brief Determine if one set of radar values are not equal to another. + * @param other The otehr set of radar values. + * @return true if the two sets are not equal, false otherwise. + */ bool operator!=( const RadarValues& other ) const { return !operator==( other ); @@ -76,8 +92,10 @@ struct RadarValues #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/ScoreKeeper.h b/src/ScoreKeeper.h index c3fca1d813..3accf2e6fa 100644 --- a/src/ScoreKeeper.h +++ b/src/ScoreKeeper.h @@ -1,4 +1,4 @@ -/* ScoreKeeper - Abstract class to handle scorekeeping, stat-taking, etc. */ +/** @brief ScoreKeeper - Abstract class to handle scorekeeping, stat-taking, etc. */ #ifndef SCORE_KEEPER_H #define SCORE_KEEPER_H @@ -65,8 +65,10 @@ protected: #endif -/* - * (c) 2001-2006 Chris Danford, Glenn Maynard, Steve Checkoway +/** + * @file + * @author Chris Danford, Glenn Maynard, Steve Checkoway (c) 2001-2006 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/SongManager.cpp b/src/SongManager.cpp index 2d9bb1f737..7ed727cd74 100644 --- a/src/SongManager.cpp +++ b/src/SongManager.cpp @@ -41,6 +41,7 @@ const RString ADDITIONAL_SONGS_DIR = "/AdditionalSongs/"; const RString ADDITIONAL_COURSES_DIR = "/AdditionalCourses/"; const RString EDIT_SUBDIR = "Edits/"; +/** @brief The file that contains various random attacks. */ const RString ATTACK_FILE = "/Data/RandomAttacks.txt"; static const ThemeMetric EXTRA_COLOR ( "SongManager", "ExtraColor" ); diff --git a/src/SongManager.h b/src/SongManager.h index 50e20a7405..c62df7f23f 100644 --- a/src/SongManager.h +++ b/src/SongManager.h @@ -1,4 +1,4 @@ -/* SongManager - Holder for all Songs and Steps. */ +/** @brief SongManager - Holder for all Songs and Steps. */ #ifndef SONGMANAGER_H #define SONGMANAGER_H @@ -21,9 +21,12 @@ struct lua_State; #include "RageTexturePreloader.h" #include "RageUtil.h" +/** @brief The max number of edit steps a profile can have. */ const int MAX_EDIT_STEPS_PER_PROFILE = 200; +/** @brief The max number of edit courses a profile can have. */ const int MAX_EDIT_COURSES_PER_PROFILE = 20; +/** @brief The holder for the Songs and its Steps. */ class SongManager { public: @@ -181,8 +184,10 @@ extern SongManager* SONGMAN; // global and accessable from anywhere in our progr #endif -/* - * (c) 2001-2004 Chris Danford, Glenn Maynard +/** + * @file + * @author Chris Danford, Glenn Maynard (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/SongUtil.cpp b/src/SongUtil.cpp index e9e59fedb0..6e075c3334 100644 --- a/src/SongUtil.cpp +++ b/src/SongUtil.cpp @@ -280,7 +280,11 @@ void SongUtil::AdjustDuplicateSteps( Song *pSong ) * These are confusing, and they're ambiguous when passed to GetStepsByID. */ } } - +/** + * @brief Remove the initial whitespace characters. + * @param s the string to left trim. + * @return the trimmed string. + */ static RString RemoveInitialWhitespace( RString s ) { size_t i = s.find_first_not_of(" \t\r\n"); diff --git a/src/SongUtil.h b/src/SongUtil.h index be42f8a7c9..3d2aa5956e 100644 --- a/src/SongUtil.h +++ b/src/SongUtil.h @@ -1,4 +1,4 @@ -/* SongUtil - Utility functions that deal with Song. */ +/** @brief SongUtil - Utility functions that deal with Song. */ #ifndef SONG_UTIL_H #define SONG_UTIL_H @@ -13,6 +13,7 @@ class Steps; class Profile; class XNode; +/** @brief The criteria for dealing with songs. */ class SongCriteria { public: @@ -22,12 +23,26 @@ public: enum Selectable { Selectable_Yes, Selectable_No, Selectable_DontCare } m_Selectable; bool m_bUseSongAllowedList; vector m_vpSongAllowedList; + /** @brief How many songs does this take max? Don't use this if it's -1. */ int m_iMaxStagesForSong; // don't filter if -1 // float m_fMinBPM; // don't filter if -1 // float m_fMaxBPM; // don't filter if -1 - enum Tutorial { Tutorial_Yes, Tutorial_No, Tutorial_DontCare } m_Tutorial; - enum Locked { Locked_Locked, Locked_Unlocked, Locked_DontCare } m_Locked; + /** @brief Is this song used for tutorial purposes? */ + enum Tutorial + { + Tutorial_Yes, /**< This song is used for tutorial purposes. */ + Tutorial_No, /**< This song is not used for tutorial purposes. */ + Tutorial_DontCare /**< This song can or cannot be used for tutorial purposes. */ + } m_Tutorial; + /** @brief Is this song used for locking/unlocking purposes? */ + enum Locked + { + Locked_Locked, /**< This song is a locked song. */ + Locked_Unlocked, /**< This song is an unlocked song. */ + Locked_DontCare /**< This song can or cannot be locked or unlocked. */ + } m_Locked; + /** @brief Set up some initial song criteria. */ SongCriteria() { m_bUseSongGenreAllowedList = false; @@ -40,9 +55,20 @@ public: m_Locked = Locked_DontCare; } + /** + * @brief Determine if the song matches the current criteria. + * @param p the song to compare against the criteria. + * @return true of the song matches the criteria, false otherwise. + */ bool Matches( const Song *p ) const; + /** + * @brief Determine if two sets of criteria are equivalent. + * @param other the other criteria. + * @return true if the two sets of criteria are equal, false otherwise. + */ bool operator==( const SongCriteria &other ) const { +/** @brief A quick way to match every part of the song criterium. */ #define X(x) (x == other.x) return X(m_sGroupName) && @@ -58,9 +84,15 @@ public: X(m_Locked); #undef X } + /** + * @brief Determine if two sets of criteria are not equivalent. + * @param other the other criteria. + * @return true if the two sets of criteria are not equal, false otherwise. + */ bool operator!=( const SongCriteria &other ) const { return !operator==( other ); } }; +/** @brief A set of song utilities to make working with songs easier. */ namespace SongUtil { void GetSteps( @@ -114,6 +146,14 @@ namespace SongUtil int CompareSongPointersByGroup(const Song *pSong1, const Song *pSong2); + /** + * @brief Determine if the requested description for an edit is unique. + * @param pSong the song the edit is for. + * @param st the steps type for the edit. + * @param sPreferredDescription the requested description. + * @param pExclude the steps that want the description. + * @return true if it is unique, false otherwise. + */ bool IsEditDescriptionUnique( const Song* pSong, StepsType st, const RString &sPreferredDescription, const Steps *pExclude ); RString MakeUniqueEditDescription( const Song* pSong, StepsType st, const RString &sPreferredDescription ); bool ValidateCurrentEditStepsDescription( const RString &sAnswer, RString &sErrorOut ); @@ -160,8 +200,10 @@ public: #endif -/* - * (c) 2001-2004 Chris Danford, Glenn Maynard +/** + * @file + * @author Chris Danford, Glenn Maynard (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/Steps.cpp b/src/Steps.cpp index 02d46b5dda..852c5b0b47 100644 --- a/src/Steps.cpp +++ b/src/Steps.cpp @@ -397,7 +397,7 @@ void Steps::SetCachedRadarValues( const RadarValues v[NUM_PLAYERS] ) // lua start #include "LuaBinding.h" - +/** @brief Allow Lua to have access to the Steps. */ class LunaSteps: public Luna { public: diff --git a/src/Steps.h b/src/Steps.h index 36c7f382a5..532857381a 100644 --- a/src/Steps.h +++ b/src/Steps.h @@ -1,4 +1,4 @@ -/* Steps - Holds note information for a Song. A Song may have one or more Notes. */ +/** @brief Steps - Holds note information for a Song. A Song may have one or more Notes. */ #ifndef STEPS_H #define STEPS_H @@ -14,12 +14,20 @@ class Profile; class NoteData; struct lua_State; +/** + * @brief Allow only 12 characters for the length of edits. + * + * This is a holdover from In The Groove: this may perhaps be not needed in the future. + */ const int MAX_EDIT_STEPS_DESCRIPTION_LENGTH = 12; +/** @brief The collective note pattern and information of the Steps that are played. */ class Steps { public: + /** @brief Set up the Steps with initial values. */ Steps(); + /** @brief Destroy the Steps that are no longer needed. */ ~Steps(); // initializers @@ -29,17 +37,51 @@ public: void Compress() const; void Decompress() const; - bool IsAutogen() const { return parent != NULL; } // Was created by autogen? + /** + * @brief Determine if these steps were created by the autogenerator. + * @return true if they were, false otherwise. + */ + bool IsAutogen() const { return parent != NULL; } - // Use a special value of difficulty + /** + * @brief Determine if this set of Steps is an edit. + * + * Edits have a special value of difficulty to make it easy to determine. + * @return true if this is an edit, false otherwise. + */ bool IsAnEdit() const { return m_Difficulty == Difficulty_Edit; } + /** + * @brief Determine if this set of Steps is a player edit. + * + * Player edits also have to be loaded from a player's profile slot, not the machine. + * @return true if this is a player edit, false otherwise. */ bool IsAPlayerEdit() const { return IsAnEdit() && GetLoadedFromProfileSlot() < ProfileSlot_Machine; } + /** + * @brief Determine if these steps were loaded from a player's profile. + * @return true if they were from a player profile, false otherwise. + */ bool WasLoadedFromProfile() const { return m_LoadedFromProfile != ProfileSlot_Invalid; } ProfileSlot GetLoadedFromProfileSlot() const { return m_LoadedFromProfile; } + /** + * @brief Retrieve the description used for this edit. + * @return the description used for this edit. + */ RString GetDescription() const { return Real()->m_sDescription; } + /** + * @brief Retrieve the difficulty used for this edit. + * @return the difficulty used for this edit. + */ Difficulty GetDifficulty() const { return Real()->m_Difficulty; } + /** + * @brief Retrieve the meter used for this edit. + * @return the meter used for this edit. + */ int GetMeter() const { return Real()->m_iMeter; } const RadarValues& GetRadarValues( PlayerNumber pn ) const { return Real()->m_CachedRadarValues[pn]; } + /** + * @brief Retrieve the author credit used for this edit. + * @return the author credit used for this edit. + */ RString GetCredit() const { return Real()->m_sCredit; } void SetFilename( RString fn ) { m_sFilename = fn; } @@ -77,7 +119,10 @@ private: inline const Steps *Real() const { return parent ? parent : this; } void DeAutogen( bool bCopyNoteData = true ); /* If this Steps is autogenerated, make it a real Steps. */ - /* If this Steps is autogenerated, this will point to the autogen + /** + * @brief Identify this Steps' parent. + * + * If this Steps is autogenerated, this will point to the autogen * source. If this is true, m_sNoteDataCompressed will always be empty. */ const Steps *parent; @@ -88,23 +133,35 @@ private: mutable bool m_bNoteDataIsFilled; mutable RString m_sNoteDataCompressed; + /** @brief The name of the file where these steps are stored. */ RString m_sFilename; - bool m_bSavedToDisk; // true if this was loaded from disk or has been saved to disk. - ProfileSlot m_LoadedFromProfile; // ProfileSlot_Invalid if wasn't loaded from a profile + /** @brief true if these Steps were loaded from or saved to disk. */ + bool m_bSavedToDisk; + /** @brief What profile was used? This is ProfileSlot_Invalid if not from a profile. */ + ProfileSlot m_LoadedFromProfile; /* These values are pulled from the autogen source first, if there is one. */ - mutable unsigned m_iHash; // only used if m_Difficulty == Difficulty_Edit - RString m_sDescription; // Edit name, or something meaningful - Difficulty m_Difficulty; // difficulty classification - int m_iMeter; // difficulty rating from MIN_METER to MAX_METER + /** @brief The hash of the steps. This is used only for Edit Steps. */ + mutable unsigned m_iHash; + /** @brief The name of the edit, or some other useful description. + This used to also contain the step author's name. */ + RString m_sDescription; + /** @brief The difficulty that these steps are assigned to. */ + Difficulty m_Difficulty; + /** @brief The numeric difficulty of the Steps, ranging from MIN_METER to MAX_METER. */ + int m_iMeter; + /** @brief The radar values used for each player. */ RadarValues m_CachedRadarValues[NUM_PLAYERS]; - RString m_sCredit; // Step author + /** @brief The name of the person who created the Steps. */ + RString m_sCredit; }; #endif -/* - * (c) 2001-2004 Chris Danford, Glenn Maynard +/** + * @file + * @author Chris Danford, Glenn Maynard (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a