Give @briefs to all namespaces.

This will force recompilation of all files.

src/BackgroundUtil.h

@@ -1,5 +1,3 @@
-/* BackgroundUtil - Shared background-related routines. */
-
 #ifndef BackgroundUtil_H
 #define BackgroundUtil_H
 
@@ -61,7 +59,7 @@ struct BackgroundChange
 
 	RString GetTextDescription() const;
 };
-
+/** @brief Shared background-related routines. */
 namespace BackgroundUtil
 {
 	void SortBackgroundChangesArray( vector<BackgroundChange> &vBackgroundChanges );

src/EnumHelper.h

@@ -27,7 +27,7 @@ struct EnumTraits
 };
 template<typename T> LuaReference EnumTraits<T>::StringToEnum;
 template<typename T> LuaReference EnumTraits<T>::EnumToString;
-
+/** @brief Lua helpers for Enumerators. */
 namespace Enum
 {
 	template<typename T>

src/FontCharmaps.h

@@ -1,7 +1,6 @@
-/* FontCharmaps - Defines common frame to character mappings for Fonts. */
 #ifndef FONT_CHARMAPS_H
 #define FONT_CHARMAPS_H
-
+/** @brief Defines common frame to character mappings for Fonts. */
 namespace FontCharmaps
 {
 	extern const wchar_t M_SKIP;

src/GameLoop.h

@@ -1,8 +1,6 @@
-/* GameLoop - Main rendering and update loop. */
-
 #ifndef GAME_LOOP_H
 #define GAME_LOOP_H
-
+/** @brief Main rendering and update loop. */
 namespace GameLoop
 {
 	void RunGameLoop();

src/GamePreferences.h

@@ -3,7 +3,7 @@
 
 #include "Preference.h"
 #include "GameConstantsAndTypes.h"
-
+/** @brief Quick access to other variables. */
 namespace GamePreferences
 {
 	extern Preference<CoinMode> m_CoinMode;

src/JsonUtil.h

@@ -1,11 +1,9 @@
-/* JsonUtil - Utilities for handling JSON data. */
-
 #ifndef JsonUtil_H
 #define JsonUtil_H
 
 class RageFileBasic;
 #include "jsoncpp/include/json/value.h"
-
+/** @brief Utilities for handling JSON data. */
 namespace JsonUtil
 {
 	bool LoadFromString( Json::Value &root, RString sData, RString &sErrorOut );

src/LuaManager.cpp

@@ -33,6 +33,7 @@ static Impl *pImpl = NULL;
 	#pragma warning (disable : 4611)
 #endif
 
+/** @brief Utilities for working with Lua. */
 namespace LuaHelpers
 {
 	template<> void Push<bool>( lua_State *L, const bool &Object );
@@ -70,6 +71,7 @@ void LuaManager::UnsetGlobal( const RString &sName )
 	Release( L );
 }
 
+/** @brief Utilities for working with Lua. */
 namespace LuaHelpers
 {
 	template<> void Push<bool>( lua_State *L, const bool &Object ) { lua_pushboolean( L, Object ); }

src/LuaManager.h

@@ -47,6 +47,7 @@ private:
 extern LuaManager *LUA;
 
 
+/** @brief Utilities for working with Lua. */
 namespace LuaHelpers
 {
 	/* Load the given script with the given name. On success, the resulting

src/LuaReference.cpp

@@ -158,6 +158,7 @@ RString LuaReference::Serialize() const
 	return sRet;
 }
 
+/** @brief Utilities for working with Lua. */
 namespace LuaHelpers
 {
 	template<> bool FromStack<LuaReference>( lua_State *L, LuaReference &Object, int iOffset )
@@ -200,6 +201,7 @@ void LuaTable::Get( Lua *L, const RString &sKey )
 	lua_remove( L, -2 ); // remove self
 }
 
+/** @brief Utilities for working with Lua. */
 namespace LuaHelpers
 {
 	template<> void Push<LuaReference>( lua_State *L, const LuaReference &Object ) 

src/MessageManager.h

@@ -207,7 +207,14 @@ public:
 	bool operator != ( const T &other ) const { return val != other; }
 };
 
-namespace LuaHelpers { template<class T> void Push( lua_State *L, const BroadcastOnChange<T> &Object ) { LuaHelpers::Push<T>( L, Object.Get() ); } }
+/** @brief Utilities for working with Lua. */
+namespace LuaHelpers
+{
+	template<class T> void Push( lua_State *L, const BroadcastOnChange<T> &Object ) 
+	{ 
+		LuaHelpers::Push<T>( L, Object.Get() );
+	} 
+}
 
 template<class T, int N>
 class BroadcastOnChange1D

src/NotesLoaderBMS.h

@@ -1,10 +1,8 @@
-/* BMSLoader - reads a Song from a set of .BMS files. */
-
 #ifndef NOTES_LOADER_BMS_H
 #define NOTES_LOADER_BMS_H
 
 class Song;
-
+/** @brief Reads a Song from a set of .BMS files. */
 namespace BMSLoader
 {
 	void GetApplicableFiles( const RString &sPath, vector<RString> &out );

src/NotesLoaderKSF.h

@@ -1,10 +1,8 @@
-/* KSFLoader - Reads a Song from a set of .KSF files. */
-
 #ifndef NOTES_LOADER_KSF_H
 #define NOTES_LOADER_KSF_H
 
 class Song;
-
+/** @brief Reads a Song from a set of .KSF files. */
 namespace KSFLoader
 {
 	void GetApplicableFiles( const RString &sPath, vector<RString> &out );

src/NotesLoaderMidi.cpp

@@ -562,7 +562,10 @@ bool MidiFileIn :: readVariableLength( unsigned long *value )
 
 	return true;
 } 
-
+/**
+ * @brief Utilities for working with the Guitar mode.
+ *
+ * Is this going to be kept in sm-ssc? */
 namespace Guitar
 {
 	enum GuitarDifficulty { easy, medium, hard, expert, NUM_GuitarDifficulty };

src/NotesLoaderMidi.h

@@ -1,10 +1,8 @@
-/* MidiLoader - Reads a Song from a .mid file. */
-
 #ifndef NotesLoaderMidi_H
 #define NotesLoaderMidi_H
 
 class Song;
-
+/** @brief Reads a Song from a .mid file. */
 namespace MidiLoader
 {
 	void GetApplicableFiles( const RString &sPath, vector<RString> &out );

src/NotesLoaderSM.h

@@ -1,5 +1,3 @@
-/* SMLoader - Reads a Song from an .SM file. */
-
 #ifndef NotesLoaderSM_H
 #define NotesLoaderSM_H
 
@@ -9,7 +7,7 @@ class MsdFile;
 class Song;
 class Steps;
 class TimingData;
-
+/** @brief Reads a Song from an .SM file. */
 namespace SMLoader
 {
 	void LoadFromSMTokens( RString sStepsType, RString sDescription, RString sDifficulty,
@@ -29,8 +27,10 @@ namespace SMLoader
 
 #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/Preference.h

@@ -121,6 +121,7 @@ private:
 	void (*m_pfnValidate)(T& val);
 };
 
+/** @brief Utilities for working with Lua. */
 namespace LuaHelpers { template<typename T> void Push( lua_State *L, const Preference<T> &Object ) { LuaHelpers::Push<T>( L, Object.Get() ); } }
 
 template <class T>

src/RageDisplay_OGL_Helpers.h

@@ -30,6 +30,7 @@
 /* Not in glext.h: */
 typedef bool (APIENTRY * PWSWAPINTERVALEXTPROC) (int interval);
 
+/** @brief Utilities for working with the RageDisplay. */
 namespace RageDisplay_OGL_Helpers
 {
 	void Init();

src/RageException.h

@@ -1,8 +1,9 @@
-/* RageException - Class for throwing fatal errors. */
-
 #ifndef RAGE_EXCEPTION_H
 #define RAGE_EXCEPTION_H
-
+/**
+ * @brief Namespace for throwing fatal errors.
+ *
+ * The original documentation stated this was a class for some reason. */
 namespace RageException
 {
 	void NORETURN Throw( const char *fmt, ... ) PRINTF(1,2);

src/RageFile.cpp

@@ -424,7 +424,7 @@ public:
 };
 
 LUA_REGISTER_CLASS( RageFile )
-
+/** @brief Utilities for working with RageFiles. */
 namespace RageFileUtil
 {
 	int CreateRageFile( lua_State *L )

src/RageFile.h

@@ -83,7 +83,7 @@ private:
 	int		m_Mode;
 };
 
-/* Convenience wrappers for reading binary files. */
+/** @brief Convenience wrappers for reading binary files. */
 namespace FileReading
 {
 	/* On error, these set sError to the error message.  If sError is already

src/RageFileManager.h

@@ -1,8 +1,6 @@
-/* RageFileManager - File utilities and high-level manager for RageFile objects. */
-
 #ifndef RAGE_FILE_MANAGER_H
 #define RAGE_FILE_MANAGER_H
-
+/** @brief Constants for working with the RageFileManager. */
 namespace RageFileManagerUtil
 {
 	extern RString sInitialWorkingDirectory;
@@ -12,7 +10,7 @@ namespace RageFileManagerUtil
 class RageFileDriver;
 class RageFileBasic;
 struct lua_State;
-
+/** @brief File utilities and high-level manager for RageFile objects. */
 class RageFileManager
 {
 public:

src/RageFileManager_ReadAhead.h

@@ -2,7 +2,7 @@
 #define RAGE_FILE_MANAGER_READAHEAD_H
 
 #include "RageFileBasic.h"
-
+/** @brief Utilities for reading the RageFiles. */
 namespace RageFileManagerReadAhead
 {
 	void Init();

src/RageSoundReader_Resample_Good.cpp

@@ -396,7 +396,7 @@ int PolyphaseFilter::NumInputsForOutputSamples( const State &State, int iOut, in
 
 	return iIn;
 }
-
+/** @brief Utilities for working with the PolyphaseFilter cache. */
 namespace PolyphaseFilterCache
 {
 	/* Cache filter data, and reuse it without copying.  All operations after creation

src/RageSoundUtil.h

@@ -1,8 +1,6 @@
-/* RageSoundUtil - simple utilities that operate on sound buffers. */
-
 #ifndef RAGE_SOUND_UTIL_H
 #define RAGE_SOUND_UTIL_H
-
+/** @brief Simple utilities that operate on sound buffers. */
 namespace RageSoundUtil
 {
 	void Attenuate( float *pBuf, int iSamples, float fVolume );

src/RageSurfaceUtils.h

@@ -8,6 +8,7 @@ struct RageSurfacePalette;
 struct RageSurfaceFormat;
 struct RageSurface;
 
+/** @brief Utility functions for the RageSurfaces. */
 namespace RageSurfaceUtils
 {
 	uint32_t decodepixel( const uint8_t *p, int bpp );

src/RageSurfaceUtils_Dither.h

@@ -2,6 +2,7 @@
 #define RAGE_SURFACE_UTILS_DITHER_H
 
 struct RageSurface;
+/** @brief Utility functions for the RageSurfaces. */
 namespace RageSurfaceUtils
 {
 	void OrderedDither(const RageSurface *src, RageSurface *dst);

src/RageSurfaceUtils_Palettize.h

@@ -4,6 +4,7 @@
 #define RAGE_SURFACE_UTILS_PALETTIZE
 
 struct RageSurface;
+/** @brief Utility functions for the RageSurfaces. */
 namespace RageSurfaceUtils
 {
 	void Palettize( RageSurface *&pImg, int iColors=256, bool bDither=true );

src/RageSurfaceUtils_Zoom.h

@@ -2,6 +2,7 @@
 #define RAGE_SURFACE_UTILS_ZOOM_H
 
 struct RageSurface;
+/** @brief Utility functions for the RageSurfaces. */
 namespace RageSurfaceUtils
 {
 	void Zoom( RageSurface *&src, int width, int height );

src/RageSurface_Load.h

@@ -2,6 +2,7 @@
 #define RAGE_SURFACE_LOAD_H
 
 struct RageSurface;
+/** @brief Utility functions for the RageSurfaces. */
 namespace RageSurfaceUtils
 {
 	enum OpenResult

src/RageSurface_Save_BMP.h

@@ -5,6 +5,7 @@
 
 struct RageSurface;
 class RageFile;
+/** @brief Utility functions for the RageSurfaces. */
 namespace RageSurfaceUtils
 {
 	bool SaveBMP( RageSurface *surface, RageFile &f );

src/RageSurface_Save_JPEG.cpp

@@ -7,6 +7,7 @@
 #include "RageFile.h"
 
 #undef FAR /* fix for VC */
+/** @brief A helper to get the jpeg lib. */
 namespace jpeg
 {
 	extern "C"

src/RageSurface_Save_JPEG.h

@@ -5,6 +5,7 @@
 
 struct RageSurface;
 class RageFile;
+/** @brief Utility functions for the RageSurfaces. */
 namespace RageSurfaceUtils
 {
 	bool SaveJPEG( RageSurface *surface, RageFile &f, bool bHighQual=true );

src/RageSurface_Save_PNG.h

@@ -5,6 +5,7 @@
 
 struct RageSurface;
 class RageFile;
+/** @brief Utility functions for the RageSurfaces. */
 namespace RageSurfaceUtils
 {
 	bool SavePNG( RageSurface *pImg, RageFile &f, RString &sError );

src/RageTypes.cpp

@@ -73,7 +73,7 @@ RString RageColor::NormalizeColorString( RString sColor )
 		return "";
 	return c.ToString();
 }
-
+/** @brief Utilities for working with Lua. */
 namespace LuaHelpers
 {
 	template<> bool FromStack<RageColor>( lua_State *L, RageColor &Object, int iOffset )

src/RageUtil.h

@@ -615,6 +615,7 @@ int GetFileSizeInBytes( const RString &sFilePath );
 void FixSlashesInPlace( RString &sPath );
 void CollapsePath( RString &sPath, bool bRemoveLeadingDot=false );
 
+/** @brief Utilities for converting the RStrings. */
 namespace StringConversion
 {
 	template<typename T>

src/RageUtil_CachedObject.h

@@ -1,5 +1,3 @@
-/* CachedObject - cached object pointers with automatic invalidation. */
-
 #ifndef RAGE_UTIL_CACHED_OBJECT_H
 #define RAGE_UTIL_CACHED_OBJECT_H
 
@@ -7,13 +5,15 @@
 
 template<typename T>
 class CachedObjectPointer;
-
+/** @brief Utilities for working with the 
+ <a class="el" href="class_cachedobject.html">CachedObjects</a>. */
 namespace CachedObjectHelpers
 {
 	void Lock();
 	void Unlock();
 }
 
+/** @brief Cached object pointers with automatic invalidation. */
 template<typename T>
 class CachedObject
 {

src/ScreenManager.cpp

@@ -81,6 +81,7 @@ static Preference<bool> g_bPruneFonts( "PruneFonts", true );
 // Screen registration
 static map<RString,CreateScreenFn>	*g_pmapRegistrees = NULL;
 
+/** @brief Utility functions for the ScreenManager. */
 namespace ScreenManagerUtil
 {
 	// in draw order first to last

src/ScreenMessage.h

@@ -17,14 +17,14 @@ extern const ScreenMessage SM_LoseFocus;
 extern const ScreenMessage SM_Pause;
 extern const ScreenMessage SM_Success;
 extern const ScreenMessage SM_Failure;
-
+/** @brief Helpers for the ScreenMessages. */
 namespace ScreenMessageHelpers
 {
 	ScreenMessage ToScreenMessage( const RString & Name );
 	RString	ScreenMessageToString( ScreenMessage SM );
 };
 
-// Automatically generate a unique ScreenMessage value
+/** @brief Automatically generate a unique ScreenMessage value */
 #define AutoScreenMessage( x ) \
 	const ScreenMessage x = ScreenMessageHelpers::ToScreenMessage( #x )
 

src/StdString.h

@@ -1,5 +1,3 @@
-/** @brief StdString - std::string convenience wrapper. */
-
 // =============================================================================
 //  FILE:  StdString.h
 //  AUTHOR:	Joe O'Leary (with outside help noted in comments)
@@ -122,29 +120,29 @@ void MakeLower( char *p, size_t iLen );
 void MakeUpper( wchar_t *p, size_t iLen );
 void MakeLower( wchar_t *p, size_t iLen );
 
-// =============================================================================
-// INLINE FUNCTIONS ON WHICH CSTDSTRING RELIES
-//
-// Usually for generic text mapping, we rely on preprocessor macro definitions
-// to map to string functions.  However the CStdStr<> template cannot use
-// macro-based generic text mappings because its character types do not get
-// resolved until template processing which comes AFTER macro processing.  In
-// other words, UNICODE is of little help to us in the CStdStr template
-//
-// Therefore, to keep the CStdStr declaration simple, we have these inline
-// functions.  The template calls them often.  Since they are inline (and NOT
-// exported when this is built as a DLL), they will probably be resolved away
-// to nothing. 
-//
-// Without these functions, the CStdStr<> template would probably have to broken
-// out into two, almost identical classes.  Either that or it would be a huge,
-// convoluted mess, with tons of "if" statements all over the place checking the
-// size of template parameter CT.
-// 
-// In several cases, you will see two versions of each function.  One version is
-// the more portable, standard way of doing things, while the other is the
-// non-standard, but often significantly faster Visual C++ way.
-// =============================================================================
+/**
+ * @brief Inline functions on which CStdString relies on.
+ *
+ * Usually for generic text mapping, we rely on preprocessor macro definitions
+ * to map to string functions.  However the CStdStr<> template cannot use
+ * macro-based generic text mappings because its character types do not get
+ * resolved until template processing which comes AFTER macro processing.  In
+ * other words, UNICODE is of little help to us in the CStdStr template.
+ *
+ * Therefore, to keep the CStdStr declaration simple, we have these inline
+ * functions.  The template calls them often.  Since they are inline (and NOT
+ * exported when this is built as a DLL), they will probably be resolved away
+ * to nothing. 
+ *
+ * Without these functions, the CStdStr<> template would probably have to broken
+ * out into two, almost identical classes.  Either that or it would be a huge,
+ * convoluted mess, with tons of "if" statements all over the place checking the
+ * size of template parameter CT.
+ * 
+ * In several cases, you will see two versions of each function.  One version is
+ * the more portable, standard way of doing things, while the other is the
+ * non-standard, but often significantly faster Visual C++ way.
+ */
 namespace StdString
 {
 // -----------------------------------------------------------------------------

src/StepMania.h

@@ -7,6 +7,7 @@ class VideoModeParams;
 
 int main( int argc, char* argv[] );
 
+/** @brief Utility functions for controlling the whole game. */
 namespace StepMania
 {
 	void ApplyGraphicOptions();

src/Trail.h

@@ -10,7 +10,8 @@ class Song;
 class Steps;
 struct lua_State;
 
-/** @brief One such Song and Step in the entire Trail. */
+/** @brief One such Song and 
+ * <a class="el" href="class_steps.html">Step</a> in the entire Trail. */
 struct TrailEntry
 {
 	TrailEntry(): 
@@ -24,9 +25,13 @@ struct TrailEntry
 	}
 	void GetAttackArray( AttackArray &out ) const;
 
+	/** @brief The Song involved in the entry. */
 	Song*		pSong;
+	/** @brief The <a class="el" href="class_steps.html">Step</a> involved in the entry. */
 	Steps*		pSteps;
+	/** @brief The Modifiers applied for the whole Song. */
 	RString		Modifiers;
+	/** @brief The Attacks that will take place durring the Song. */
 	AttackArray	Attacks;
 	/**
 	 * @brief Is this Song and its Step meant to be a secret?