More doxygen. Compilation redoing warning.

src/Banner.h

@@ -1,4 +1,4 @@
-/* Banner - The song/course's banner displayed in SelectMusic/Course. */
+/** @brief Banner - The song/course's banner displayed in SelectMusic/Course. */
 
 #ifndef BANNER_H
 #define BANNER_H
@@ -11,6 +11,7 @@ class Course;
 class Character;
 class UnlockEntry;
 
+/** @brief The characteristics of a Banner */
 class Banner : public Sprite
 {
 public:
@@ -24,7 +25,11 @@ public:
 
 	virtual void Update( float fDeltaTime );
 
-	void LoadFromSong( Song* pSong );		// NULL means no song
+	/**
+	 * @brief Attempt to load the banner from a song.
+	 * @param pSong the song in question. If NULL, there is no song.
+	 */
+	void LoadFromSong( Song* pSong );
 	void LoadMode();
 	void LoadFromSongGroup( RString sSongGroup );
 	void LoadFromCourse( const Course *pCourse );
@@ -54,8 +59,10 @@ protected:
 
 #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

src/MsdFile.h

@@ -1,47 +1,107 @@
-/* MsdFile - Read .SSC, .SM, .DWI, and .MSD files. */
+/** @brief MsdFile - Read .SSC, .SM, .DWI, and .MSD files. */
 
 #ifndef MSDFILE_H
 #define MSDFILE_H
 
+/** @brief The class that reads the various .SSC, .SM, .DWI, and .MSD files. */
 class MsdFile  
 {
 public:
-	/* #param:param:param:param; <- one whole value */
+	/**
+	 * @brief The list of params found in the files.
+	 *
+	 * Note that #param:param:param:parm; is one whole value. */
 	struct value_t
 	{
+		/** @brief The list of parameters. */
 		vector<RString> params;
-
+		/**
+		 * @brief Access the proper parameter.
+		 * @param i the index.
+		 * @return the proper parameter.
+		 */
 		RString operator[]( unsigned i ) const { if( i >= params.size() ) return RString(); return params[i]; }
 	};
 
+	/** @brief Remove the MSDFile. */
 	virtual ~MsdFile() { }
 
-	// Returns true if successful, false otherwise.
+	/**
+	 * @brief Attempt to read an MSD file.
+	 * @param sFilePath the path to the file.
+	 * @param bUnescape a flag to see if we need to unescape values.
+	 * @return its success or failure.
+	 */
 	bool ReadFile( RString sFilePath, bool bUnescape );
+	/**
+	 * @brief Attempt to read an MSD file.
+	 * @param sString the path to the file.
+	 * @param bUnescape a flag to see if we need to unescape values.
+	 * @return its success or failure.
+	 */
 	void ReadFromString( const RString &sString, bool bUnescape );
 
+	/**
+	 * @brief Should an error take place, have an easy place to get it.
+	 * @return the current error. */
 	RString GetError() const { return error; }
 
+	/**
+	 * @brief Retrieve the number of values for each tag.
+	 * @return the nmber of values. */
 	unsigned GetNumValues() const { return values.size(); }
+	/**
+	 * @brief Get the number of parameters for the current index.
+	 * @param val the current value index.
+	 * @return the number of params.
+	 */
 	unsigned GetNumParams( unsigned val ) const { if( val >= GetNumValues() ) return 0; return values[val].params.size(); }
+	/**
+	 * @brief Get the specified value.
+	 * @param val the current value index.
+	 * @return The specified value.
+	 */
 	const value_t &GetValue( unsigned val ) const { ASSERT(val < GetNumValues()); return values[val]; }
+	/**
+	 * @brief Retrieve the specified parameter.
+	 * @param val the current value index.
+	 * @param par the current parameter index.
+	 * @return the parameter in question.
+	 */
 	RString GetParam( unsigned val, unsigned par ) const;
 
 
 private:
+	/**
+	 * @brief Attempt to read an MSD file from the buffer.
+	 * @param buf the buffer containing the MSD file.
+	 * @param len the length of the buffer.
+	 * @param bUnescape a flag to see if we need to unescape values.
+	 */
 	void ReadBuf( const char *buf, int len, bool bUnescape );
+	/**
+	 * @brief Add a new parameter.
+	 * @param buf the new parameter.
+	 * @param len the length of the new parameter.
+	 */
 	void AddParam( const char *buf, int len );
+	/**
+	 * @brief Add a new value.
+	 */
 	void AddValue();
 
+	/** @brief The list of values. */
 	vector<value_t> values;
+	/** @brief The error string. */
 	RString error;
 };
 
 #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

src/RageUtil.h

@@ -1,4 +1,4 @@
-/* RageUtil - Miscellaneous helper macros and functions. */
+/** @brief RageUtil - Miscellaneous helper macros and functions. */
 
 #ifndef RAGE_UTIL_H
 #define RAGE_UTIL_H
@@ -7,12 +7,16 @@
 #include <vector>
 class RageFileDriver;
 
+/** @brief Safely delete pointers. */
 #define SAFE_DELETE(p)       do { delete (p);     (p)=NULL; } while( false )
+/** @brief Safely delete array pointers. */
 #define SAFE_DELETE_ARRAY(p) do { delete[] (p);   (p)=NULL; } while( false )
 
+/** @brief Zero out the memory. */
 #define ZERO(x)	memset(&(x), 0, sizeof(x))
+/** @brief Copy from a to b. */
 #define COPY(a,b) do { ASSERT(sizeof(a)==sizeof(b)); memcpy(&(a), &(b), sizeof(a)); } while( false )
-
+/** @brief Get the length of the array. */
 #define ARRAYLEN(a) (sizeof(a) / sizeof((a)[0]))
 
 /* Common harmless mismatches.  All min(T,T) and max(T,T) cases are handled
@@ -26,13 +30,19 @@ inline unsigned long min( unsigned long a, unsigned int b ) { return a < b? a:b;
 inline unsigned long max( unsigned int a, unsigned long b ) { return a > b? a:b; }
 inline unsigned long max( unsigned long a, unsigned int b ) { return a > b? a:b; }
 
+/** @brief If outside the range from low to high, bring it within range. */
 #define clamp(val,low,high)		( max( (low), min((val),(high)) ) )
 
-// Scales x so that l1 corresponds to l2 and h1 corresponds to h2.  Does not modify x, MUST assign the result to something!
+/**
-// Do the multiply before the divide to that integer scales have more precision.
+ * @brief Scales x so that l1 corresponds to l2 and h1 corresponds to h2.
+ *
+ * This does not modify x, so it MUST assign the result to something!
+ * Do the multiply before the divide to that integer scales have more precision.
+ *
+ * One such example: SCALE(x, 0, 1, L, H); interpolate between L and H.
+ */
 #define SCALE(x, l1, h1, l2, h2)	(((x) - (l1)) * ((h2) - (l2)) / ((h1) - (l1)) + (l2))
 
-// Like SCALE(x, 0, 1, L, H); interpolate between L and H.
 template<typename T, typename U>
 inline U lerp( T x, U l, U h )
 {
@@ -259,14 +269,21 @@ typedef MersenneTwister RandomGen;
 
 extern RandomGen g_RandomNumberGenerator;
 
-// [0.0f,1.0f)
+/**
+ * @brief Generate a random float between 0 inclusive and 1 exclusive.
+ * @return the random float.
+ */
 inline float RandomFloat()
 {
 	return g_RandomNumberGenerator() / 2147483648.0f;
 }
 
-
+/**
-// Returns a float between fLow and fHigh inclusive
+ * @brief Return a float between the low and high values.
+ * @param fLow the low value, inclusive.
+ * @param fHigh the high value, inclusive.
+ * @return the random float.
+ */
 inline float RandomFloat( float fLow, float fHigh )
 {
 	return SCALE( RandomFloat(), 0.0f, 1.0f, fLow, fHigh );
@@ -639,8 +656,10 @@ void GetConnectsDisconnects( const vector<T> &before, const vector<T> &after, ve
 
 #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