added better comments for stim::filename

David Mayerich
1 parent dc913a73
Showing 1 changed file with 40 additions and 36 deletions Show diff stats
stim/parser/filename.h
@@ -110,7 +110,7 @@ public:
 	}
  
  
-
+	/// Outputs the file name (including prefix and extension)
 	std::string get_name(){
 		if(prefix == "" && ext == "")
 			return "";
@@ -118,14 +118,18 @@ public:
 			return prefix + "." + ext;
 	}
  
+	/// Output the file extension only (usually three characters after a '.')
 	std::string get_extension(){
 		return ext;
 	}
  
+	/// Output the file prefix only (name before the extension)
 	std::string get_prefix(){
 		return prefix;
 	}
  
+	/// Output the entire path (not including the filename)
+	///		ex. "c:\this\is\the\directory\"
 	std::string dir(){
 		std::stringstream ss;
  
@@ -146,17 +150,17 @@ public:
  
 	}
  
+	/// Output the entire string, including the path and filename
+	///		ex. "c:\this\is\a\directory\file.txt"
 	std::string str(){
-
-		std::stringstream ss;
-
-		ss<<dir()<<get_name();
-
-		return ss.str();
+		std::stringstream ss;					//create a string stream
+		ss<<dir()<<get_name();					//push the directory and filename to that stream
+		return ss.str();						//convert the stream to a string and return it
 	}
  
 	//*****************************************************************************************************************
 	// output is the directory and the prefix and the extension of the files, which are looking for in that directory.
+	/// David: I have no idea what this is doing. It looks identical to dir()
 	std::string dir_fname(){
 		std::stringstream ss;
  
@@ -182,20 +186,17 @@ public:
 	std::string f_name(std::string file_name){
 		std::stringstream ss;
  
-		//if the path is absolute
-		if(absolute){
-			//output the drive letter if in Windows
+		if(absolute){ 								//if the path is absolute
 			#ifdef _WIN32
-				ss<<drive<<":";
+				ss<<drive<<":";						//output the drive letter if in Windows
 			#endif
-			ss<<STIM_FILENAME_DIV;
+			ss<<STIM_FILENAME_DIV;					//output a path divider
 		}
  
-		//output the directory
-		for(unsigned int d = 0; d < path.size(); d++)
-			ss<<path[d]<<STIM_FILENAME_DIV;
+		for(unsigned int d = 0; d < path.size(); d++)	//for each directory in the current path
+			ss<<path[d]<<STIM_FILENAME_DIV;				//add that directory, interspersing path dividers
  
-		stim::filename fn = file_name;
+		stim::filename fn = file_name;					
 			std::string fn_prefix = fn.prefix;
 			std::string fn_ext = fn.ext;
 		ss<<fn_prefix + '.' + fn_ext;
@@ -204,38 +205,41 @@ public:
  
 	}
  
+	/// Returns a list of files using the current filename as a template.
+	/// For example:
+	///			C:\this\is\a\path\file*.txt
+	///		can be used as a template to find a series of files file001.txt, file002.txt, file003.txt, etc.
 	std::vector<stim::filename> get_list(){
-#ifdef _WIN32
-	//get a list of files matching the current template
-
+		//this is OS dependent, so we're starting with Windows
+		//the Unix version requires Boost
  
-		//stim::filename file_path;
-		stim::filename filepath(dir_fname());
+#elif _WIN32
+		stim::filename filepath(dir_fname());									//initialize filepath with the mask					
  
-		HANDLE            hFind = INVALID_HANDLE_VALUE;
+		HANDLE            hFind = INVALID_HANDLE_VALUE;							//allocate data structures for looping through files
 		WIN32_FIND_DATAA   FindFileData;
-		std::vector<stim::filename> file_list;
+		std::vector<stim::filename> file_list;									//initialize a list to hold all matching filenames
  
-		hFind = FindFirstFileA((filepath.str().c_str()), &FindFileData);
+		hFind = FindFirstFileA((filepath.str().c_str()), &FindFileData);		//find the first file that matches the specified file path
  
-		if (hFind == INVALID_HANDLE_VALUE) {
-			printf ("Invalid file handle. Error is %u.\n", GetLastError());
+		if (hFind == INVALID_HANDLE_VALUE) { 									//if there are no matching files
+			printf ("Invalid file handle. Error is %u.\n", GetLastError());		//print an error
 		}
 		else {
-			std::string file_name = FindFileData.cFileName;					//get the file name
-			std::string file_path = dir();
-			stim::filename current_file(file_path + file_name);
-			file_list.push_back(current_file);
+			std::string file_name = FindFileData.cFileName;						//save the file name
+			std::string file_path = dir();										//the file is in the specified directory, so save it
+			stim::filename current_file(file_path + file_name);					//create a stim::filename structure representing this file
+			file_list.push_back(current_file);									//push the new stim::filename to the file list
  
 			// List all the other files in the directory.
-			while (FindNextFileA(hFind, &FindFileData) != 0){
-				file_name = FindFileData.cFileName;
-				current_file = (f_name(file_name));
-				file_list.push_back(current_file);
+			while (FindNextFileA(hFind, &FindFileData) != 0){ 					//iterate until there are no more matching files
+				file_name = FindFileData.cFileName;								//save the next file
+				current_file = (f_name(file_name));								//append the directory
+				file_list.push_back(current_file);								//push it to the list
 			}
-			FindClose(hFind);
+			FindClose(hFind);													//close the file data structure
 		}
-		return file_list;
+		return file_list;														//return the list of files
  
 #elif BOOST_PRECOMPILED