From dbe5df006dd269bd32090958b6ea2fd2be21874e Mon Sep 17 00:00:00 2001
From: Jason Felds <jafelds@gmail.com>
Date: Sat, 12 Feb 2011 21:59:36 -0500
Subject: [PATCH] NotesLoaderDWI mostly doxygen-ated.

---
 src/NotesLoaderDWI.cpp | 53 ++++++++++++++++++++++++++++++++++++++----
 src/NotesLoaderDWI.h   | 21 ++++++++++++++---
 2 files changed, 66 insertions(+), 8 deletions(-)

diff --git a/src/NotesLoaderDWI.cpp b/src/NotesLoaderDWI.cpp
index 69dab5eade..59781ba774 100644
--- a/src/NotesLoaderDWI.cpp
+++ b/src/NotesLoaderDWI.cpp
@@ -15,6 +15,7 @@
 
 static std::map<int,int> g_mapDanceNoteToNoteDataColumn;
 
+/** @brief The different types of core DWI arrows and pads. */
 enum
 {
 	DANCE_NOTE_NONE = 0,
@@ -32,6 +33,14 @@ enum
 	DANCE_NOTE_PAD2_RIGHT
 };
 
+/**
+ * @brief Turn the individual character to the proper note.
+ * @param c The character in question.
+ * @param i The player.
+ * @param col1Out The first result based on the character.
+ * @param col2Out The second result based on the character.
+ * @param sPath the path to the file.
+ */
 static void DWIcharToNote( char c, GameController i, int &note1Out, int &note2Out, const RString &sPath )
 {
 	switch( c )
@@ -79,6 +88,14 @@ static void DWIcharToNote( char c, GameController i, int &note1Out, int &note2Ou
 	}
 }
 
+/**
+ * @brief Determine the note column[s] to place notes.
+ * @param c The character in question.
+ * @param i The player.
+ * @param col1Out The first result based on the character.
+ * @param col2Out The second result based on the character.
+ * @param sPath the path to the file.
+ */
 static void DWIcharToNoteCol( char c, GameController i, int &col1Out, int &col2Out, const RString &sPath )
 {
 	int note1, note2;
@@ -95,11 +112,18 @@ static void DWIcharToNoteCol( char c, GameController i, int &col1Out, int &col2O
 		col2Out = -1;
 }
 
-/* Ack.  DWI used to use <...> to indicate 1/192nd notes; at some
+/**
+ * @brief Determine if the note in question is a 192nd note.
+ *
+ * DWI used to use <...> to indicate 1/192nd notes; at some
  * point, <...> was changed to indicate jumps, and `' was used for
  * 1/192nds.  So, we have to do a check to figure out what it really
  * means.  If it contains 0s, it's most likely 192nds; otherwise,
- * it's most likely a jump.  Search for a 0 before the next >: */
+ * it's most likely a jump.  Search for a 0 before the next >: 
+ * @param sStepData the step data.
+ * @param pos the position of the step data.
+ * @return true if it's a 192nd note, false otherwise.
+ */
 static bool Is192( const RString &sStepData, size_t pos )
 {
 	while( pos < sStepData.size() )
@@ -113,9 +137,20 @@ static bool Is192( const RString &sStepData, size_t pos )
 	
 	return false;
 }
-
+/** @brief All DWI files use 4 beats per measure. */
 const int BEATS_PER_MEASURE = 4;
 
+/**
+ * @brief Look through the notes tag to extract the data.
+ * @param sMode the steps type.
+ * @param sDescription the difficulty.
+ * @param sNumFeet the meter.
+ * @param sStepData1 the guaranteed step data.
+ * @param sStepData2 used if sMode is double or couple.
+ * @param out the step data.
+ * @param sPath the path to the file.
+ * @return the success or failure of the operation.
+ */
 static bool LoadFromDWITokens( 
 	RString sMode, 
 	RString sDescription,
@@ -336,8 +371,16 @@ static bool LoadFromDWITokens(
 	return true;
 }
 
-/* This value can be in either "HH:MM:SS.sssss", "MM:SS.sssss", "SSS.sssss"
- * or milliseconds. */
+/**
+ * @brief Turn the DWI style timestamp into a compatible time for our system.
+ *
+ * This value can be in either "HH:MM:SS.sssss", "MM:SS.sssss", "SSS.sssss"
+ * or milliseconds.
+ * @param arg1 Either hours, minutes, or seconds, depending on other args.
+ * @param arg2 Either minutes or seconds, depending on other args.
+ * @param arg3 Seconds if not empty.
+ * @return the proper timestamp.
+ */
 static float ParseBrokenDWITimestamp( const RString &arg1, const RString &arg2, const RString &arg3 )
 {
 	if( arg1.empty() )
diff --git a/src/NotesLoaderDWI.h b/src/NotesLoaderDWI.h
index 49099e0811..99f0f0a33a 100644
--- a/src/NotesLoaderDWI.h
+++ b/src/NotesLoaderDWI.h
@@ -1,4 +1,4 @@
-/* DWILoader - reads a Song from a .DWI file. */
+/** @brief DWILoader - reads a Song from a .DWI file. */
 
 #ifndef NOTES_LOADER_DWI_H
 #define NOTES_LOADER_DWI_H
@@ -7,16 +7,31 @@
 
 class Song;
 
+/** @brief The DWILoader handles parsing the .dwi file. */
 namespace DWILoader
 {
+	/**
+	 * @brief Retrieve the list of .dwi files.
+	 * @param sPath a const reference to the path on the hard drive to check.
+	 * @param out a vector of files found in the path.
+	 */
 	void GetApplicableFiles( const RString &sPath, vector<RString> &out );
+	/**
+	 * @brief Attempt to load a song from a specified path.
+	 * @param sPath a const reference to the path on the hard drive to check.
+	 * @param out a reference to the Song that will retrieve the song information.
+	 * @param BlacklistedImages a set of images that aren't used.
+	 * @return its success or failure.
+	 */
 	bool LoadFromDir( const RString &sPath, Song &out, set<RString> &BlacklistedImages );
 }
 
 #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