[doc] Add actual documentation to all classes

DATabase/Core/Generate.cs

@@ -11,6 +11,9 @@ using SabreTools.Helper;
 
 namespace SabreTools
 {
+	/// <summary>
+	/// Generate a DAT from the data in the database
+	/// </summary>
 	class Generate
 	{
 		// Private instance variables
@@ -24,6 +27,15 @@ namespace SabreTools
 		private Dictionary<int, string> _headers;
 		private Logger _logger;
 
+		/// <summary>
+		/// Initialize a Generate object with the given information
+		/// </summary>
+		/// <param name="systems">Comma-separated list of systems to be included in the DAT (blank means all)</param>
+		/// <param name="sources">Comma-separated list of sources to be included in the DAT (blank means all)</param>
+		/// <param name="connectionString">Connection string for SQLite</param>
+		/// <param name="logger">Logger object for file or console output</param>
+		/// <param name="norename">True if files should not be renamed with system and/or source in merged mode (default false)</param>
+		/// <param name="old">True if the output file should be in RomVault format (default false)</param>
 		public Generate(string systems, string sources, string connectionString, Logger logger, bool norename = false, bool old = false)
 		{
 			_systems = systems;
@@ -43,6 +55,10 @@ namespace SabreTools
 			_headers.Add(241, "snes.xml");  // Self-created to deal with various headers
 		}
 
+		/// <summary>
+		/// Generate a DAT file that is represented by the data in the Generate object.
+		/// </summary>
+		/// <returns>True if the file could be created, false otherwise</returns>
 		public bool Export()
 		{
 			// Check to see if the source is an import-only. If so, tell the user and exit
@@ -251,6 +267,10 @@ namespace SabreTools
 			return true;
 		}
 
+		/// <summary>
+		/// Preprocess the rom data that is to be included in the outputted DAT
+		/// </summary>
+		/// <returns>A List of RomData objects containing all information about the files</returns>
 	    public List<RomData> ProcessRoms()
 		{
 			List<RomData> roms = new List<RomData>();
@@ -429,7 +449,9 @@ JOIN checksums
 		}
 	}
 
-	// Intermediate struct for holding and processing rom data
+	/// <summary>
+	/// Intermediate struct for holding and processing rom data
+	/// </summary>
 	public struct RomData
 	{
 		public string Manufacturer;

DATabase/Core/Import.cs

@@ -32,6 +32,10 @@ namespace SabreTools
 	7) You should be done! Unless your DAT is of a custom format, it should be taken care of on import.
 		i. If custom handling is needed on import, look for "SuperDAT" for an example
 	*/
+
+	/// <summary>
+	/// Import data into the database from existing DATs
+	/// </summary>
 	public class Import
 	{
 		// Private instance variables
@@ -56,6 +60,9 @@ namespace SabreTools
 		private static string _redumpDatePattern = @"(\d{4})(\d{2})(\d{2}) (\d{2})-(\d{2})-(\d{2})";
 		private static string _tosecDatePattern = @"(\d{4})-(\d{2})-(\d{2})";
 
+		/// <summary>
+		/// Possible DAT import classes
+		/// </summary>
 		private enum DatType
 		{
 			none = 0,
@@ -73,7 +80,12 @@ namespace SabreTools
 			get { return _filepath; }
 		}
 
-		// Constructor
+		/// <summary>
+		/// Initialize an Import object with the given information
+		/// </summary>
+		/// <param name="filepath">Path to the file that is going to be imported</param>
+		/// <param name="connectionString">Connection string for SQLite</param>
+		/// <param name="logger">Logger object for file or console output</param>
 		public Import(string filepath, string connectionString, Logger logger)
 		{
 			if (File.Exists(filepath))
@@ -89,7 +101,10 @@ namespace SabreTools
 			_logger = logger;
 		}
 
-		// Import the data from file into the database
+		/// <summary>
+		/// Import the data from file into the database
+		/// </summary>
+		/// <returns>True if the data was imported, false otherwise</returns>
 		public bool ImportData ()
 		{
 			// Determine which dattype we have
@@ -353,7 +368,7 @@ namespace SabreTools
 							// If we find a rom or disk, add it
 							if (node.NodeType == XmlNodeType.Element && (child.Name == "rom" || child.Name == "disk"))
 							{
-								AddRomHelper(
+								AddRom(
 									child.Name,
 									gameid,
 									child.Attributes["name"].Value,
@@ -377,7 +392,7 @@ namespace SabreTools
 											// If we find a rom or disk, add it
 											if (data.NodeType == XmlNodeType.Element && (data.Name == "rom" || data.Name == "disk"))
 											{
-												AddRomHelper(
+												AddRom(
 													data.Name,
 													gameid,
 													data.Attributes["name"].Value,
@@ -401,6 +416,13 @@ namespace SabreTools
 			return true;
 		}
 
+		/// <summary>
+		/// Add a game to the database if it doesn't already exist
+		/// </summary>
+		/// <param name="sysid">System ID for the game to be added with</param>
+		/// <param name="machinename">Name of the game to be added</param>
+		/// <param name="srcid">Source ID for the game to be added with</param>
+		/// <returns>Game ID of the inserted (or found) game, -1 on error</returns>
 		private long AddGame(int sysid, string machinename, int srcid)
 		{
 			// WoD gets rid of anything past the first "(" or "[" as the name, we will do the same
@@ -457,7 +479,19 @@ namespace SabreTools
 			return gameid;
 		}
 
-		private bool AddRomHelper(string romtype, long gameid, string name, string date, int size, string crc, string md5, string sha1)
+		/// <summary>
+		/// Add a file to the database if it doesn't already exist
+		/// </summary>
+		/// <param name="romtype">File type (either "rom" or "disk")</param>
+		/// <param name="gameid">ID of the parent game to be mapped to</param>
+		/// <param name="name">File name</param>
+		/// <param name="date">Last updated date</param>
+		/// <param name="size">File size in bytes</param>
+		/// <param name="crc">CRC32 hash of the file</param>
+		/// <param name="md5">MD5 hash of the file</param>
+		/// <param name="sha1">SHA-1 hash of the file</param>
+		/// <returns>True if the file exists or could be added, false on error</returns>
+		private bool AddRom(string romtype, long gameid, string name, string date, int size, string crc, string md5, string sha1)
 		{
 			// WOD origninally stripped out any subdirs from the imported files, we do the same
 			name = Path.GetFileName(name);

DATabase/DATabase.cs

@@ -7,6 +7,9 @@ using SabreTools.Helper;
 
 namespace SabreTools
 {
+	/// <summary>
+	/// Entry class for the DATabase application
+	/// </summary>
 	class DATabase
 	{
 		private static Logger logger;
@@ -22,7 +25,11 @@ namespace SabreTools
 +-----------------------------------------------------------------------------+
 ";
 
-		static void Main(string[] args)
+		/// <summary>
+		/// Start menu or use supplied parameters
+		/// </summary>
+		/// <param name="args">String array representing command line parameters</param>
+		public static void Main(string[] args)
 		{
 			// Perform initial setup and verification
 			logger = new Logger(false, "database.log");
@@ -169,6 +176,9 @@ namespace SabreTools
 			return;
 		}
 
+		/// <summary>
+		/// Print the program header
+		/// </summary>
 		private static void PrintHeader()
 		{
 			ConsoleColor formertext = Console.ForegroundColor;
@@ -180,6 +190,9 @@ namespace SabreTools
 			Console.BackgroundColor = formerback;
 		}
 
+		/// <summary>
+		/// Show the text-based main menu
+		/// </summary>
 		private static void ShowMainMenu()
 		{
 			Console.Clear();
@@ -249,6 +262,9 @@ Make a selection:
 			Console.WriteLine("Thank you for using DATabase!");
 		}
 
+		/// <summary>
+		/// Show the help dialog
+		/// </summary>
 		private static void Help()
 		{
 			Console.Clear();
@@ -294,6 +310,9 @@ Database Options:
 			return;
 		}
 
+		/// <summary>
+		/// Show the text-based import menu
+		/// </summary>
 		private static void ImportMenu()
 		{
 			string selection = "";
@@ -317,6 +336,10 @@ or 'b' to go back to the previous menu:");
 			return;
 		}
 
+		/// <summary>
+		/// Wrap importing a file or folder into the database
+		/// </summary>
+		/// <param name="filename">File or folder to be imported</param>
 		private static void InitImport(string filename)
 		{
 			Console.Clear();
@@ -347,6 +370,9 @@ or 'b' to go back to the previous menu:");
 			return;
 		}
 
+		/// <summary>
+		/// Show the text-based generate menu
+		/// </summary>
 		private static void GenerateMenu()
 		{
 			string selection = "", systems = "", sources = "";
@@ -399,6 +425,23 @@ Make a selection:
 			return;
 		}
 
+		/// <summary>
+		/// Wrap generating a DAT from the database
+		/// </summary>
+		/// <param name="systems">Comma-separated list of systems to be included in the DAT (blank means all)</param>
+		/// <param name="sources">Comma-separated list of sources to be included in the DAT (blank means all)</param>
+		/// <param name="norename">True if files should not be renamed with system and/or source in merged mode (default false)</param>
+		/// <param name="old">True if the output file should be in RomVault format (default false)</param>
+		private static void InitGenerate(string systems, string sources, bool norename, bool old)
+		{
+			Generate gen = new Generate(systems, sources, _connectionString, logger, norename, old);
+			gen.Export();
+			return;
+		}
+
+		/// <summary>
+		/// Show the text-based generate all menu
+		/// </summary>
 		private static void GenerateAllMenu()
 		{
 			string selection = "";
@@ -437,14 +480,11 @@ Make a selection:
 			return;
 		}
 
-		/// TODO: Make this safe for auto-generating multiple files (such as auto-generate)
+		/// <summary>
-		private static void InitGenerate(string systems, string sources, bool norename, bool old)
+		/// Wrap generating all standard DATs from the database
-		{
+		/// </summary>
-			Generate gen = new Generate(systems, sources, _connectionString, logger, norename, old);
+		/// <param name="norename">True if files should not be renamed with system and/or source in merged mode (default false)</param>
-			gen.Export();
+		/// <param name="old">True if the output file should be in RomVault format (default false)</param>
-			return;
-		}
-
 		private static void InitGenerateAll(bool norename, bool old)
 		{
 			// Generate system-merged
@@ -533,6 +573,9 @@ Make a selection:
 			return;
 		}
 
+		/// <summary>
+		/// Show the text-based conversion menu
+		/// </summary>
 		private static void ConvertMenu()
 		{
 			string selection = "";
@@ -557,6 +600,10 @@ or 'b' to go back to the previous menu:
 			return;
 		}
 
+		/// <summary>
+		/// Wrap converting DAT file from RomValut to XML
+		/// </summary>
+		/// <param name="filename"></param>
 		private static void InitConvert(string filename)
 		{
 			if (File.Exists(filename))
@@ -579,6 +626,10 @@ or 'b' to go back to the previous menu:
 			return;
 		}
 
+		/// <summary>
+		/// List sources in the database
+		/// </summary>
+		/// <param name="all">True to list all sources regardless if there is a game associated or not</param>
 		private static void ListSources(bool all = false)
 		{
 			string query = @"
@@ -610,6 +661,10 @@ ORDER BY sources.name COLLATE NOCASE";
 			return;
 		}
 
+		/// <summary>
+		/// List systems in the database
+		/// </summary>
+		/// <param name="all">True to list all systems regardless if there is a game associated or not</param>
 		private static void ListSystems(bool all = false)
 		{
 			string query = @"
@@ -641,6 +696,9 @@ ORDER BY systems.manufacturer, systems.system";
 			return;
 		}
 
+		/// <summary>
+		/// Show the text-based add and remove menu
+		/// </summary>
 		private static void AddRemoveMenu()
 		{
 			string selection = "", manufacturer = "", system = "", name = "", url = "";
@@ -703,6 +761,11 @@ Make a selection:
 			return;
 		}
 
+		/// <summary>
+		/// Wrap adding a new source to the database
+		/// </summary>
+		/// <param name="name">Source name</param>
+		/// <param name="url">Source URL(s)</param>
 		private static void InitAddSource(string name, string url)
 		{
 			if (DBTools.AddSource(name, url, _connectionString))
@@ -715,6 +778,10 @@ Make a selection:
 			}
 		}
 
+		/// <summary>
+		/// Wrap removing an existing source from the database
+		/// </summary>
+		/// <param name="id">Source ID to be removed from the database</param>
 		private static void InitRemoveSource(string sourceid)
 		{
 			int srcid = -1;
@@ -735,6 +802,11 @@ Make a selection:
 			}
 		}
 
+		/// <summary>
+		/// Wrap adding a new system to the database
+		/// </summary>
+		/// <param name="manufacturer">Manufacturer name</param>
+		/// <param name="system">System name</param>
 		private static void InitAddSystem(string manufacturer, string system)
 		{
 			if (DBTools.AddSystem(manufacturer, system, _connectionString))
@@ -747,6 +819,10 @@ Make a selection:
 			}
 		}
 
+		/// <summary>
+		/// Wrap removing an existing system from the database
+		/// </summary>
+		/// <param name="id">System ID to be removed from the database</param>
 		private static void InitRemoveSystem(string systemid)
 		{
 			int sysid = -1;

DATabase/Helper/Converters.cs

@@ -4,13 +4,22 @@ using System.Xml.Linq;
 
 namespace SabreTools.Helper
 {
+	/// <summary>
+	/// Provide DAT conversion functionality
+	/// </summary>
 	class Converters
 	{
+		// Regex matching patterns
 		private static string _headerPattern = @"(^.*?) \($";
 		private static string _romPattern = @"^\s+((?:rom)|(?:disk)) \( (name) ""(.*?)"" (?:(size) (.*?) )?(?:(crc) (.*?))?(?:(md5) (.*?) )?(?:(sha1) (.*?) )?\)";
 		private static string _itemPattern = @"^\s+(.*?) ""(.*?)""";
 		private static string _endPattern = @"^\s*\)\s*$";
 
+		/// <summary>
+		/// Convert a RomVault style DAT to an XML derived DAT
+		/// </summary>
+		/// <param name="filecontents">Array of strings representing the input file</param>
+		/// <returns>XElement representing the output XML DAT file</returns>
 		public static XElement RomVaultToXML (string[] filecontents)
 		{
 			XElement elem = new XElement("datafile");

DATabase/Helper/DBTools.cs

@@ -4,8 +4,16 @@ using System.IO;
 
 namespace SabreTools.Helper
 {
+	/// <summary>
+	/// All general database operations
+	/// </summary>
 	class DBTools
 	{
+		/// <summary>
+		/// Ensure that the databse exists and has the proper schema
+		/// </summary>
+		/// <param name="db">Name of the databse</param>
+		/// <param name="connectionString">Connection string for SQLite</param>
 		public static void EnsureDatabase(string db, string connectionString)
 		{
 			// Make sure the file exists
@@ -91,6 +99,13 @@ CREATE TABLE IF NOT EXISTS systems (
 			}
 		}
 
+		/// <summary>
+		/// Add a new source to the database if it doesn't already exist
+		/// </summary>
+		/// <param name="name">Source name</param>
+		/// <param name="url">Source URL(s)</param>
+		/// <param name="connectionString">Connection string for SQLite</param>
+		/// <returns>True if the source existed or could be added, false otherwise</returns>
 		public static bool AddSource(string name, string url, string connectionString)
 		{
 			string query = "SELECT id, name, url FROM sources WHERE name='" + name + "'";
@@ -130,6 +145,12 @@ CREATE TABLE IF NOT EXISTS systems (
 			return true;
 		}
 
+		/// <summary>
+		/// Remove an existing source from the database
+		/// </summary>
+		/// <param name="id">Source ID to be removed from the database</param>
+		/// <param name="connectionString">Connection string for SQLite</param>
+		/// <returns>True if the source was removed, false otherwise</returns>
 		public static bool RemoveSource(int id, string connectionString)
 		{
 			string query = "DELETE FROM sources WHERE id=" + id;
@@ -143,6 +164,13 @@ CREATE TABLE IF NOT EXISTS systems (
 			}
 		}
 
+		/// <summary>
+		/// Add a new system to the database if it doesn't already exist
+		/// </summary>
+		/// <param name="manufacturer">Manufacturer name</param>
+		/// <param name="system">System name</param>
+		/// <param name="connectionString">Connection string for SQLite</param>
+		/// <returns>True if the system existed or could be added, false otherwise</returns>
 		public static bool AddSystem(string manufacturer, string system, string connectionString)
 		{
 			string query = "SELECT id, manufacturer, system FROM systems WHERE manufacturer='" + manufacturer + "' AND system='" + system + "'";
@@ -168,6 +196,12 @@ CREATE TABLE IF NOT EXISTS systems (
 			return true;
 		}
 
+		/// <summary>
+		/// Remove an existing system from the database
+		/// </summary>
+		/// <param name="id">System ID to be removed from the database</param>
+		/// <param name="connectionString">Connection string for SQLite</param>
+		/// <returns>True if the system was removed, false otherwise</returns>
 		public static bool RemoveSystem(int id, string connectionString)
 		{
 			string query = "DELETE FROM systems WHERE id=" + id;

DATabase/Helper/Logger.cs

@@ -3,6 +3,9 @@ using System.IO;
 
 namespace SabreTools.Helper
 {
+	/// <summary>
+	/// Log either to file or to the console
+	/// </summary>
 	public class Logger
 	{
 		// Private instance variables
@@ -28,12 +31,21 @@ namespace SabreTools.Helper
 			}
 		}
 
+		/// <summary>
+		/// Initialize a Logger object with the given information
+		/// </summary>
+		/// <param name="tofile">True if file should be written to instead of console</param>
+		/// <param name="filename">Optional filename representing log location</param>
 		public Logger(bool tofile, string filename = "")
 		{
 			_tofile = tofile;
 			_filename = filename;
 		}
 
+		/// <summary>
+		/// Start logging by opening output file (if necessary)
+		/// </summary>
+		/// <returns>True if the logging was started correctly, false otherwise</returns>
 		public bool Start()
 		{
 			if (!_tofile)
@@ -54,6 +66,10 @@ namespace SabreTools.Helper
 			return true;
 		}
 
+		/// <summary>
+		/// End logging by closing output file (if necessary)
+		/// </summary>
+		/// <returns>True if the logging was ended correctly, false otherwise</returns>
 		public bool Close()
 		{
 			if (!_tofile)
@@ -74,6 +90,11 @@ namespace SabreTools.Helper
 			return true;
 		}
 
+		/// <summary>
+		/// Write the given string to the log output
+		/// </summary>
+		/// <param name="output">String to be written log</param>
+		/// <returns>True if the output could be written, false otherwise</returns>
 		public bool Log(string output)
 		{
 			// If we're writing to console, just write the string

DATabase/Helper/Remapping.cs

@@ -5,14 +5,21 @@ using System.Xml;
 
 namespace SabreTools.Helper
 {
+	/// <summary>
+	/// Contains all remappings of known import classes
+	/// </summary>
 	class Remapping
 	{
+		// Remapping classes represented by dictionaries
 		public static Dictionary<string, string> MAME = new Dictionary<string, string>();
 		public static Dictionary<string, string> NoIntro = new Dictionary<string, string>();
 		public static Dictionary<string, string> Redump = new Dictionary<string, string>();
 		public static Dictionary<string, string> TOSEC = new Dictionary<string, string>();
 		public static Dictionary<string, string> TruRip = new Dictionary<string, string>();
 
+		/// <summary>
+		/// Create all remappings to be used by the program
+		/// </summary>
 		public static void CreateRemappings()
 		{
 			// Create array of dictionary names
@@ -28,6 +35,10 @@ namespace SabreTools.Helper
 			}
         }
 
+		/// <summary>
+		/// Create a remapping from XML
+		/// </summary>
+		/// <param name="mapping">Name of the mapping to be populated</param>
 		private static void RemappingHelper(string mapping)
 		{
 			// Read in remapping from file

DATabase/Helper/Style.cs

@@ -2,9 +2,16 @@
 
 namespace SabreTools.Helper
 {
+	/// <summary>
+	/// Include character normalization and replacement mappings
+	/// </summary>
 	public class Style
 	{
-		// Replace accented characters
+		/// <summary>
+		/// Replace accented characters
+		/// </summary>
+		/// <param name="input">String to be parsed</param>
+		/// <returns>String with characters replaced</returns>
 		public static string NormalizeChars(string input)
 		{
 			string[,] charmap = {
@@ -53,7 +60,11 @@ namespace SabreTools.Helper
 			return input;
 		}
 
-		// Replace special characters and patterns
+		/// <summary>
+		/// Replace special characters and patterns
+		/// </summary>
+		/// <param name="input">String to be parsed</param>
+		/// <returns>String with characters replaced</returns>
 		public static string SearchPattern(string input)
 		{
 			string[,] charmap = {
@@ -93,8 +104,12 @@ namespace SabreTools.Helper
 			return input;
 		}
 
-		// Convert Cyrillic lettering to Latin lettering
+		/// <summary>
-		public static string RussianToLatin (string input)
+		/// Convert Cyrillic lettering to Latin lettering
+		/// </summary>
+		/// <param name="input">String to be parsed</param>
+		/// <returns>String with characters replaced</returns>
+		public static string RussianToLatin(string input)
 		{
 			string [,] charmap = {
 					{ "А", "A" }, { "Б", "B" }, { "В", "V" }, { "Г", "G" }, { "Д", "D" },

Deheader/Deheader.cs

@@ -6,12 +6,19 @@ using System.Text.RegularExpressions;
 
 namespace SabreTools
 {
+	/// <summary>
+	/// Entry class for the Deheader application
+	/// </summary>
 	class Deheader
 	{
 		private static Dictionary<string, int> types;
 		private static bool save;
 		private static string help = @"Deheader.exe [-s] filename|dirname";
 
+		/// <summary>
+		/// Start deheader operation with supplied parameters
+		/// </summary>
+		/// <param name="args">String array representing command line parameters</param>
 		static void Main(string[] args)
 		{
 			// Type mapped to header size (in decimal bytes)
@@ -65,6 +72,10 @@ namespace SabreTools
 			}
 		}
 
+		/// <summary>
+		/// Detect and remove header from the given file
+		/// </summary>
+		/// <param name="file">Name of the file to be parsed</param>
 		private static void DetectRemoveHeader(string file)
 		{
 			// Open the file in read mode