From 255209685c826ff72075204daaebca42bb8905df Mon Sep 17 00:00:00 2001
From: Jason Felds <jafelds@gmail.com>
Date: Fri, 18 Feb 2011 17:31:35 -0500
Subject: [PATCH] More doxygen.

---
 src/Song.cpp |  9 +++++++--
 src/Song.h   | 46 +++++++++++++++++++++++++++++++++++-----------
 2 files changed, 42 insertions(+), 13 deletions(-)

diff --git a/src/Song.cpp b/src/Song.cpp
index be2852325b..0906ee7f6d 100644
--- a/src/Song.cpp
+++ b/src/Song.cpp
@@ -38,13 +38,18 @@
 
 /** @brief The version of the .ssc file format. */
 const static float VERSION_NUMBER = 0.52f;
-const int FILE_CACHE_VERSION = 164;	// increment this to invalidate cache
+/**
+ * @brief The internal version of the cache for StepMania.
+ *
+ * Increment this value to invalidate the current cache. */
+const int FILE_CACHE_VERSION = 164;
 
+/** @brief How long does a song sample last by default? */
 const float DEFAULT_MUSIC_SAMPLE_LENGTH = 12.f;
 
 static Preference<float>	g_fLongVerSongSeconds( "LongVerSongSeconds", 60*2.5f );
 static Preference<float>	g_fMarathonVerSongSeconds( "MarathonVerSongSeconds", 60*5.f );
-static Preference<bool>	g_BackUpAllSongSaves( "BackUpAllSongSaves", false );
+static Preference<bool>		g_BackUpAllSongSaves( "BackUpAllSongSaves", false );
 
 static const char *InstrumentTrackNames[] = {
 	"Guitar",
diff --git a/src/Song.h b/src/Song.h
index 7c8f845966..360eb8f129 100644
--- a/src/Song.h
+++ b/src/Song.h
@@ -18,7 +18,9 @@ class StepsID;
 struct lua_State;
 struct BackgroundChange;
 
+/** @brief How many edits for this song can each profile have? */
 const int MAX_EDITS_PER_SONG_PER_PROFILE	= 5;
+/** @brief How many edits for this song can be available? */
 const int MAX_EDITS_PER_SONG			= 5*NUM_ProfileSlot;
 
 extern const int FILE_CACHE_VERSION;
@@ -47,11 +49,12 @@ enum InstrumentTrack
 const RString& InstrumentTrackToString( InstrumentTrack it );
 InstrumentTrack StringToInstrumentTrack( const RString& s );
 
+/** @brief The collection of lyrics for the Song. */
 struct LyricSegment
 {
-	float	m_fStartTime;
-	RString m_sLyric;
-	RageColor m_Color;
+	float	m_fStartTime; /** @brief When does the lyric show up? */
+	RString m_sLyric; /** @brief The lyrics themselves. */
+	RageColor m_Color; /** @brief The color of the lyrics. */
 };
 
 class Song
@@ -81,9 +84,19 @@ public:
 	// This one takes the effort to reuse Steps pointers as best as it can
 	bool ReloadFromSongDir( RString sDir );
 
-	void TidyUpData();	// call after loading to clean up invalid data
-	void ReCalculateRadarValuesAndLastBeat();	// called by TidyUpData, and after saving
-	void TranslateTitles();	// called by TidyUpData
+	/** @brief Call this after loading a song to clean up invalid data. */
+	void TidyUpData();
+	
+	/**
+	 * @brief Get the new radar values, and determine the last beat at the same time.
+	 *
+	 * This is called by TidyUpData, after saving the Song. */
+	void ReCalculateRadarValuesAndLastBeat();
+	/**
+	 * @brief Translate any titles that aren't in english.
+	 *
+	 * This is called by TidyUpData. */
+	void TranslateTitles();	
 
 	/**
 	 * @brief Save to the new SSC file format.
@@ -93,8 +106,17 @@ public:
 	bool SaveToSSCFile( RString sPath, bool bSavingCache );
 	/** @brief Save to the SSC and SM files no matter what. */
 	void Save();
+	/** 
+	  * @brief Save the current Song to a cache file using the preferred format.
+	  * @return its success or failure. */
 	bool SaveToCacheFile();
+	/**
+	 * @brief Save the current Song to a SM file.
+	 * @return its success or failure. */
 	bool SaveToSMFile();
+	/** 
+	 * @brief Save the current Song to a DWI file if possible.
+	 * @return its success or failure. */
 	bool SaveToDWIFile();
 
 	const RString &GetSongFilePath() const;
@@ -275,11 +297,13 @@ public:
 	int GetNumStepsLoadedFromProfile( ProfileSlot slot ) const;
 	bool IsEditAlreadyLoaded( Steps* pSteps ) const;
 
-	// An array of keysound file names (e.g. "beep.wav").
-	// The index in this array corresponds to the index in TapNote.  If you 
-	// change the index in here, you must change all NoteData too.
-	// Any note that doesn't have a value in the range of this array
-	// means "this note doesn't have a keysound".
+	/**
+	 * @brief An array of keysound file names (e.g. "beep.wav").
+	 *
+	 * The index in this array corresponds to the index in TapNote.  If you 
+	 * change the index in here, you must change all NoteData too.
+	 * Any note that doesn't have a value in the range of this array
+	 * means "this note doesn't have a keysound". */
 	vector<RString> m_vsKeysoundFile;
 
 	CachedObject<Song> m_CachedObject;