More doc updates.

src/AdjustSync.h

@@ -1,14 +1,15 @@
-/* AdjustSync - Allows for adjusting the sync of a song. */
 #ifndef AdjustSync_H
 #define AdjustSync_H
 
-/* This class defines two ways of adjusting the sync of a song.
+class TimingData;
+/** 
+ * @brief Allows for adjusting the sync of a song.
+ *
+ * This class defines two ways of adjusting the sync of a song.
  * The first adjusts only the offset, "on the fly". It can adjust either the
  * song itself or the machine. The other style adjusts both the BPM and the
- * offset of the song, but it needs more data. */
+ * offset of the song, but it needs more data.
-
+ */
-class TimingData;
-
 class AdjustSync
 {
 public:
@@ -49,8 +50,10 @@ public:
 
 #endif
 
-/*
+/**
- * (c) 2003-2006 Chris Danford, John Bauer
+ * @file
+ * @author Chris Danford, John Bauer (c) 2003-2006
+ * @section LICENSE
  * All rights reserved.
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a

src/CourseUtil.h

@@ -1,5 +1,3 @@
-/** @brief CourseUtil - Utility functions that deal with Course. */
-
 #ifndef COURSEUTIL_H
 #define COURSEUTIL_H
 
@@ -13,6 +11,7 @@ class XNode;
 class CourseEntry;
 class Song;
 
+/** @brief Utility functions that deal with Courses. */
 namespace CourseUtil
 {
 	void SortCoursePointerArrayByDifficulty( vector<Course*> &vpCoursesInOut );
@@ -43,6 +42,7 @@ namespace CourseUtil
 	//RString GetSectionNameFromCourseAndSort( const Course *pCourse, SortOrder so );
 };
 
+/** @brief Utility functions that deal with Edit Courses. */
 namespace EditCourseUtil
 {
 	void UpdateAndSetTrail();

src/NoteData.h

@@ -223,6 +223,7 @@ public:
 	void LoadFromNode( const XNode* pNode );
 };
 
+/** @brief Allow a quick way to swap notedata. */
 namespace std
 {
 	template<> inline void swap<NoteData>( NoteData &nd1, NoteData &nd2 ) { nd1.swap( nd2 ); }

src/NoteDataUtil.h

@@ -1,5 +1,3 @@
-/* NoteDataUtil - Utility functions that deal with NoteData. */
-
 #ifndef NOTEDATAUTIL_H
 #define NOTEDATAUTIL_H
 
@@ -12,10 +10,12 @@ class NoteData;
 class Song;
 struct AttackArray;
 
-/* Utils for NoteData.  Things should go in here if they can be (cleanly and
+/**
- * efficiently) implemented using only NoteData's primitives; this improves
+ * @brief Utility functions that deal with NoteData.
- * abstraction and makes it much easier to change NoteData internally in
+ *
- * the future. */
+ * Things should go in here if they can be (cleanly and efficiently)
+ * implemented using only NoteData's primitives; this improves abstraction 
+ * and makes it much easier to change NoteData internally in the future. */
 namespace NoteDataUtil
 {
 	NoteType GetSmallestNoteTypeForMeasure( const NoteData &nd, int iMeasureIndex );
@@ -74,7 +74,9 @@ namespace NoteDataUtil
 	void Twister( NoteData &inout, int iStartIndex = 0, int iEndIndex = MAX_NOTE_ROW );
 	void ConvertTapsToHolds( NoteData &inout, int iSimultaneousHolds, int iStartIndex = 0, int iEndIndex = MAX_NOTE_ROW );
 
-	// Change all TAP_ADDITION_TAPs to TAP_ORIGINAL_TAPs.
+	/**
+	 * @brief Convert all taps added via transforms into original style tap notes.
+	 * @param inout the NoteData to convert. */
 	void ConvertAdditionsToRegular( NoteData &inout );
 
 	void Backwards( NoteData &inout );
@@ -100,7 +102,8 @@ namespace NoteDataUtil
 	bool RowPassesValidMask( NoteData &inout, int row, const bool bValidMask[] );
 
 	void TransformNoteData( NoteData &nd, const AttackArray &aa, StepsType st, Song* pSong );
-	void TransformNoteData( NoteData &nd, const PlayerOptions &po, StepsType st, int iStartIndex = 0, int iEndIndex = MAX_NOTE_ROW );
+	void TransformNoteData( NoteData &nd, const PlayerOptions &po, StepsType st, 
+			       int iStartIndex = 0, int iEndIndex = MAX_NOTE_ROW );
 	void AddTapAttacks( NoteData &nd, Song* pSong );
 
 	// void Scale( NoteData &nd, float fScale );

src/NoteDataWithScoring.h

@@ -1,5 +1,3 @@
-/* NoteDataWithScoring - NoteData with scores for each TapNote and HoldNote. */
-
 #ifndef NOTE_DATA_WITH_SCORING_H
 #define NOTE_DATA_WITH_SCORING_H
 
@@ -12,6 +10,7 @@ class PlayerStageStats;
 class NoteData;
 struct TapNote;
 
+/** @brief NoteData with scores for each TapNote and HoldNote. */
 namespace NoteDataWithScoring
 {
 	bool IsRowCompletelyJudged( const NoteData &in, unsigned iRow );

src/NotesLoader.h

@@ -1,5 +1,3 @@
-/* NotesLoader - Base class for step file loaders. */
-
 #ifndef NOTES_LOADER_H
 #define NOTES_LOADER_H
 
@@ -7,16 +5,31 @@
 
 class Song;
 
+/** @brief Base class for step file loaders. */
 namespace NotesLoader
 {
-	void GetMainAndSubTitlesFromFullTitle( const RString &sFullTitle, RString &sMainTitleOut, RString &sSubTitleOut );
+	/**
+	 * @brief Identify the main and sub titles from a full title.
+	 * @param sFullTitle the full title.
+	 * @param sMainTitleOut the eventual main title.
+	 * @param sSubTitleOut the ventual sub title. */
+	void GetMainAndSubTitlesFromFullTitle( const RString &sFullTitle, 
+					      RString &sMainTitleOut, RString &sSubTitleOut );
+	/**
+	 * @brief Attempt to load a Song from the given directory.
+	 * @param sPath the path to the file.
+	 * @param out the Song in question.
+	 * @param BlacklistedImages images to exclude (DWI files only for some reason).
+	 * @return its success or failure. */
 	bool LoadFromDir( const RString &sPath, Song &out, set<RString> &BlacklistedImages );
 }
 
 #endif
 
-/*
+/**
- * (c) 2001-2003,2007 Chris Danford, Glenn Maynard, Steve Checkoway
+ * @file
+ * @author Chris Danford, Glenn Maynard, Steve Checkoway (c) 2001-2003,2007
+ * @section LICENSE
  * All rights reserved.
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a

src/NotesLoaderPMS.h

@@ -1,10 +1,8 @@
-/* PMSLoader - reads a Song from a set of .PMS files. */
-
 #ifndef NOTES_LOADER_PMS_H
 #define NOTES_LOADER_PMS_H
 
 class Song;
-
+/** @brief Reads a Song from a set of .PMS files. */
 namespace PMSLoader
 {
 	void GetApplicableFiles( const RString &sPath, vector<RString> &out );
@@ -13,8 +11,10 @@ namespace PMSLoader
 
 #endif
 
-/*
+/**
- * (c) 2001-2003 Chris Danford
+ * @file
+ * @author Chris Danford (c) 2001-2003
+ * @section LICENSE
  * All rights reserved.
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a

src/NotesWriterDWI.cpp

@@ -11,98 +11,11 @@
 #include "Song.h"
 #include "Steps.h"
 
-static RString OptimizeDWIString( RString holds, RString taps );
+/**
-
+ * @brief Optimize an individual pair of characters whenever possible.
-/* Output is an angle bracket expression without angle brackets, eg. "468". */
+ * @param c1 the first character.
-static RString NotesToDWIString( const TapNote tnCols[6] )
+ * @param c2 the second character.
-{
+ * @return the one singular character. */
-	const char dirs[] = { '4', 'C', '2', '8', 'D', '6' };
-	RString taps, holds, ret;
-	for( int col = 0; col < 6; ++col )
-	{
-		switch( tnCols[col].type )
-		{
-		case TapNote::empty:
-		case TapNote::mine:
-			continue;
-		}
-
-		if( tnCols[col].type == TapNote::hold_head )
-			holds += dirs[col];
-		else
-			taps += dirs[col];
-	}
-
-	if( holds.size() + taps.size() == 0 )
-		return "0";
-
-//	RString combine = taps;
-//	for( unsigned i = 0; i < holds.size(); ++i )
-//		combine += ssprintf("%c!%c", holds[i], holds[i]);
-
-//	if( holds.size() + taps.size() > 1 )
-//		combine = ssprintf("<%s>", combine.c_str() );
-
-//	return combine;
-
-	/* More than one. */
-	return OptimizeDWIString( holds, taps );
-/*	struct DWICharLookup {
-		char c;
-		bool bCol[6];	
-	} const lookup[] = {
-		{ '0', { 0, 0, 0, 0, 0, 0 } },
-		{ '1', { 1, 0, 1, 0, 0, 0 } },
-		{ '2', { 0, 0, 1, 0, 0, 0 } },
-		{ '3', { 0, 0, 1, 0, 0, 1 } },
-		{ '4', { 1, 0, 0, 0, 0, 0 } },
-		{ '6', { 0, 0, 0, 0, 0, 1 } },
-		{ '7', { 1, 0, 0, 1, 0, 0 } },
-		{ '8', { 0, 0, 0, 1, 0, 0 } },
-		{ '9', { 0, 0, 0, 1, 0, 1 } },
-		{ 'A', { 0, 0, 1, 1, 0, 0 } },
-		{ 'B', { 1, 0, 0, 0, 0, 1 } },
-		{ 'C', { 0, 1, 0, 0, 0, 0 } },
-		{ 'D', { 0, 0, 0, 0, 1, 0 } },
-		{ 'E', { 1, 1, 0, 0, 0, 0 } },
-		{ 'F', { 0, 1, 1, 0, 0, 0 } },
-		{ 'G', { 0, 1, 0, 1, 0, 0 } },
-		{ 'H', { 0, 1, 0, 0, 0, 1 } },
-		{ 'I', { 1, 0, 0, 0, 1, 0 } },
-		{ 'J', { 0, 0, 1, 0, 1, 0 } },
-		{ 'K', { 0, 0, 0, 1, 1, 0 } },
-		{ 'L', { 0, 0, 0, 0, 1, 1 } },
-		{ 'M', { 0, 1, 0, 0, 1, 0 } },
-	};
-	const int iNumLookups = sizeof(lookup) / sizeof(*lookup);
-
-	for( int i=0; i<iNumLookups; i++ )
-	{
-		const DWICharLookup& l = lookup[i];
-		if( l.bCol[0]==bCol1 && l.bCol[1]==bCol2 && l.bCol[2]==bCol3 && l.bCol[3]==bCol4 && l.bCol[4]==bCol5 && l.bCol[5]==bCol6 )
-			return l.c;
-	}
-	LOG->Warn( "Failed to find the DWI character for the row %d %d %d %d %d %d", bCol1, bCol2, bCol3, bCol4, bCol5, bCol6 );
-	return '0';*/
-}
-
-static RString NotesToDWIString( TapNote tnCol1, TapNote tnCol2, TapNote tnCol3, TapNote tnCol4, TapNote tnCol5, TapNote tnCol6 )
-{
-	TapNote tnCols[6];
-	tnCols[0] = tnCol1;
-	tnCols[1] = tnCol2;
-	tnCols[2] = tnCol3;
-	tnCols[3] = tnCol4;
-	tnCols[4] = tnCol5;
-	tnCols[5] = tnCol6;
-	return NotesToDWIString( tnCols );
-}
-
-static RString NotesToDWIString( TapNote tnCol1, TapNote tnCol2, TapNote tnCol3, TapNote tnCol4 )
-{
-	return NotesToDWIString( tnCol1, TAP_EMPTY, tnCol2, tnCol3, TAP_EMPTY, tnCol4 );
-}
-
 static char OptimizeDWIPair( char c1, char c2 )
 {
 	typedef pair<char,char> cpair;
@@ -138,6 +51,11 @@ static char OptimizeDWIPair( char c1, char c2 )
 	return it->second;
 }
 
+/**
+ * @brief Shrink the file contents as best as possible.
+ * @param holds the holds in the file.
+ * @param taps the taps in the file.
+ * @return the optimized string. */
 RString OptimizeDWIString( RString holds, RString taps )
 {
 	/* First, sort the holds and taps in ASCII order.  This puts 2468 first.
@@ -191,8 +109,78 @@ RString OptimizeDWIString( RString holds, RString taps )
 		return ssprintf( "<%s>", ret.c_str() );
 }
 
+/**
+ * @brief Turn the Notes into a DWI string without angle brackets whenever possible.
+ * @param tnCols the columns of TapNotes in question.
+ * @return the DWI'ed string. */
+static RString NotesToDWIString( const TapNote tnCols[6] )
+{
+	const char dirs[] = { '4', 'C', '2', '8', 'D', '6' };
+	RString taps, holds, ret;
+	for( int col = 0; col < 6; ++col )
+	{
+		switch( tnCols[col].type )
+		{
+		case TapNote::empty:
+		case TapNote::mine:
+			continue;
+		}
+
+		if( tnCols[col].type == TapNote::hold_head )
+			holds += dirs[col];
+		else
+			taps += dirs[col];
+	}
+
+	if( holds.size() + taps.size() == 0 )
+		return "0";
+
+	/* More than one. */
+	return OptimizeDWIString( holds, taps );
+}
+
+/**
+ * @brief Turn the Notes into a DWI string without angle brackets whenever possible.
+ * @param tnCol1 the first column.
+ * @param tnCol2 the second column.
+ * @param tnCol3 the third column.
+ * @param tnCol4 the fourth column.
+ * @param tnCol5 the fifth column.
+ * @param tnCol6 the sisth column.
+ * @return the DWI'ed string. */
+static RString NotesToDWIString( TapNote tnCol1, TapNote tnCol2, TapNote tnCol3, 
+				 TapNote tnCol4, TapNote tnCol5, TapNote tnCol6 )
+{
+	TapNote tnCols[6];
+	tnCols[0] = tnCol1;
+	tnCols[1] = tnCol2;
+	tnCols[2] = tnCol3;
+	tnCols[3] = tnCol4;
+	tnCols[4] = tnCol5;
+	tnCols[5] = tnCol6;
+	return NotesToDWIString( tnCols );
+}
+
+/**
+ * @brief Turn the Notes into a DWI string without angle brackets whenever possible.
+ * @param tnCol1 the first column.
+ * @param tnCol2 the second column.
+ * @param tnCol3 the third column.
+ * @param tnCol4 the fourth column.
+ * @return the DWI'ed string. */
+static RString NotesToDWIString( TapNote tnCol1, TapNote tnCol2, TapNote tnCol3, TapNote tnCol4 )
+{
+	return NotesToDWIString( tnCol1, TAP_EMPTY, tnCol2, tnCol3, TAP_EMPTY, tnCol4 );
+}
+
+/** @brief The number of beats per measure for a DWI file. */
 static const int BEATS_PER_MEASURE = 4;
 
+/**
+ * @brief Write out the notes for a DWI file.
+ * @param f the file to write out to.
+ * @param out the Steps in question.
+ * @param start the starting position. */
 static void WriteDWINotesField( RageFile &f, const Steps &out, int start )
 {
 	NoteData notedata;
@@ -315,6 +303,11 @@ static void WriteDWINotesField( RageFile &f, const Steps &out, int start )
 	}
 }
 
+/**
+ * @brief Attempt to write a DWI's #NOTES tag.
+ * @param f the file to write out to.
+ * @param out the Steps in question.
+ * @return its success or failure. */
 static bool WriteDWINotesTag( RageFile &f, const Steps &out )
 {
 	if( out.GetDifficulty() == Difficulty_Edit )

src/NotesWriterDWI.h

@@ -1,18 +1,24 @@
-/* NotesWriterDWI - Writes a Song to a .DWI file. */
-
 #ifndef NOTES_WRITER_DWI_H
 #define NOTES_WRITER_DWI_H
 
 class Song;
+/** @brief Writes a Song to a .DWI file. */
 namespace NotesWriterDWI
 {
+	/**
+	 * @brief Write the song out to a file.
+	 * @param sPath the path to write the file.
+	 * @param out the Song to be written out.
+	 * @return its success or failure. */
 	bool Write( RString sPath, const Song &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

src/OptionRowHandler.h

@@ -1,5 +1,3 @@
-/* OptionRowHandler - Shows PlayerOptions and SongOptions in icon form. */
-
 #ifndef OptionRowHandler_H
 #define OptionRowHandler_H
 
@@ -84,6 +82,7 @@ struct OptionRowDefinition
 	}
 };
 
+/** @brief Shows PlayerOptions and SongOptions in icon form. */
 class OptionRowHandler
 {
 public:
@@ -130,7 +129,7 @@ public:
 	virtual RString GetScreen( int iChoice ) const { return RString(); }
 };
 
-
+/** @brief Utilities for the OptionRowHandlers. */
 namespace OptionRowHandlerUtil
 {
 	OptionRowHandler* Make( const Commands &cmds );