From 30d5812f9c13164df99dd97e127cd0f032f2df4a Mon Sep 17 00:00:00 2001 From: Jason Felds Date: Sat, 26 Feb 2011 19:31:04 -0500 Subject: [PATCH] Add more docs. --- src/LocalizedString.h | 10 +++++----- src/NoteDataWithScoring.h | 14 +++++++++++--- src/PlayerStageStats.h | 33 +++++++++++++++++++++++---------- src/Profile.h | 27 ++++++++++++++++++++------- src/Steps.h | 7 ++++--- 5 files changed, 63 insertions(+), 28 deletions(-) diff --git a/src/LocalizedString.h b/src/LocalizedString.h index d3309ea494..1e5c7256e8 100644 --- a/src/LocalizedString.h +++ b/src/LocalizedString.h @@ -1,5 +1,3 @@ -/* LocalizedString - */ - #ifndef LocalizedString_H #define LocalizedString_H @@ -10,7 +8,7 @@ public: virtual void Load( const RString& sGroup, const RString& sName ) = 0; virtual const RString &GetLocalized() const = 0; }; - +/** @brief Get a String based on the user's natural language. */ class LocalizedString { public: @@ -31,8 +29,10 @@ private: #endif -/* - * Copyright (c) 2001-2005 Chris Danford, Glenn Maynard +/** + * @file + * @author Chris Danford, Glenn Maynard (c) 2001-2005 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/NoteDataWithScoring.h b/src/NoteDataWithScoring.h index 5ae36adc56..9c8206e730 100644 --- a/src/NoteDataWithScoring.h +++ b/src/NoteDataWithScoring.h @@ -13,17 +13,25 @@ struct TapNote; /** @brief NoteData with scores for each TapNote and HoldNote. */ namespace NoteDataWithScoring { + /** + * @brief Has the current row of NoteData been judged completely? + * @param in the entire Notedata. + * @param iRow the row to check. + * @return true if it has been completley judged, or false otherwise. */ bool IsRowCompletelyJudged( const NoteData &in, unsigned iRow ); TapNoteScore MinTapNoteScore( const NoteData &in, unsigned iRow ); const TapNote &LastTapNoteWithResult( const NoteData &in, unsigned iRow ); - void GetActualRadarValues( const NoteData &in, const PlayerStageStats &pss, float fSongSeconds, RadarValues& out ); + void GetActualRadarValues( const NoteData &in, const PlayerStageStats &pss, + float fSongSeconds, RadarValues& out ); }; #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/PlayerStageStats.h b/src/PlayerStageStats.h index 373911e6b1..33e220ea45 100644 --- a/src/PlayerStageStats.h +++ b/src/PlayerStageStats.h @@ -1,5 +1,3 @@ -/* PlayerStageStats - Contains statistics for one stage of play - either one song, or a whole course. */ - #ifndef PlayerStageStats_H #define PlayerStageStats_H @@ -10,7 +8,7 @@ #include class Steps; struct lua_State; - +/** @brief Contains statistics for one stage of play - either one song, or a whole course. */ class PlayerStageStats { public: @@ -32,10 +30,18 @@ public: bool m_bJoined; vector m_vpPossibleSteps; int m_iStepsPlayed; // how many of m_vpPossibleStepshow many of m_vpPossibleSteps were played - float m_fAliveSeconds; // how far into the music did they last before failing? Updated by Gameplay, scaled by music rate. + /** + * @brief How far into the music did the Player last before failing? + * + * This is updated by Gameplay, and scaled by the music rate. */ + float m_fAliveSeconds; - /* Set if the player actually failed at any point during the song. This is always - * false in FAIL_OFF. If recovery is enabled and two players are playing, + /** + * @brief Have the Players failed at any point during the song? + * + * If FAIL_OFF is in use, this is always false. + * + * If health recovery is possible after failing (requires two players), * this is only set if both players were failing at the same time. */ bool m_bFailed; @@ -54,10 +60,15 @@ public: int m_iMaxScore; RadarValues m_radarPossible; // filled in by ScreenGameplay on start of notes RadarValues m_radarActual; - // The number of songs played and passed, respectively. + /** @brief How many songs were passed by the Player? */ int m_iSongsPassed; + /** @brief How many songs were played by the Player? */ int m_iSongsPlayed; - float m_fLifeRemainingSeconds; // used in survival + /** + * @brief How many seconds were left for the Player? + * + * This is used in the Survival mode. */ + float m_fLifeRemainingSeconds; // workout float m_iNumControllerSteps; @@ -125,8 +136,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/Profile.h b/src/Profile.h index b351656bd0..bfea1f35d1 100644 --- a/src/Profile.h +++ b/src/Profile.h @@ -1,5 +1,3 @@ -/** @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 @@ -62,7 +60,10 @@ class Song; class Steps; class Course; class Game; - +/** + * @brief Player data that persists between sessions. + * + * This can be stored on a local disk or on a memory card. */ class Profile { public: @@ -95,14 +96,20 @@ public: Song *GetMostPopularSong() const; Course *GetMostPopularCourse() const; - void AddStepTotals( int iNumTapsAndHolds, int iNumJumps, int iNumHolds, int iNumRolls, int iNumMines, int iNumHands, int iNumLifts, float fCaloriesBurned ); + void AddStepTotals( int iNumTapsAndHolds, int iNumJumps, int iNumHolds, int iNumRolls, int iNumMines, + int iNumHands, int iNumLifts, float fCaloriesBurned ); bool IsMachine() const; // Editable data RString m_sDisplayName; RString m_sCharacterID; - RString m_sLastUsedHighScoreName; // this doesn't really belong in "editable", but we need it in the smaller editable file so that it can be ready quickly. + /** + * @brief The last used name for high scoring purposes. + * + * This really shouldn't be in "editable", but it's needed in the smaller editable file + * so that it can be ready quickly. */ + RString m_sLastUsedHighScoreName; int m_iWeightPounds; // 0 == not set //RString m_sProfileImageName; // todo: add a default image -aj @@ -136,7 +143,13 @@ public: int m_iTotalHands; int m_iTotalLifts; set m_UnlockedEntryIDs; - mutable RString m_sLastPlayedMachineGuid; // mutable because we overwrite this on save, and I don't want to remove const from the whole save chain. -Chris + /** + * @brief Which machine did we play on last, based on the Guid? + * + * This is mutable because it's overwritten on save, but is usually + * const everywhere else. It was decided to keep const on the whole + * save chain and keep this mutable. -Chris */ + mutable RString m_sLastPlayedMachineGuid; mutable DateTime m_LastPlayedDate; /* These stats count twice in the machine profile if two players are playing; * that's the only approach that makes sense for ByDifficulty and ByMeter. */ @@ -217,7 +230,7 @@ public: /** - * @brief The basics for Calorie Data + * @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. diff --git a/src/Steps.h b/src/Steps.h index e87dfef458..fe1b26a5ea 100644 --- a/src/Steps.h +++ b/src/Steps.h @@ -1,5 +1,3 @@ -/** @brief Steps - Holds note information for a Song. A Song may have one or more Notes. */ - #ifndef STEPS_H #define STEPS_H @@ -21,7 +19,10 @@ struct lua_State; */ const int MAX_EDIT_STEPS_DESCRIPTION_LENGTH = 12; -/** @brief The collective note pattern and information of the Steps that are played. */ +/** + * @brief Holds note information for a Song. + * + * A Song may have one or more Notes. */ class Steps { public: