DOCUMENTATION: Added XML documentation to DiscImageChef.Core.

DiscImageChef.Core/Devices/Dumping/ATA.cs

@@ -52,8 +52,26 @@ using Tuple = DiscImageChef.Decoders.PCMCIA.Tuple;
 
 namespace DiscImageChef.Core.Devices.Dumping
 {
+    /// <summary>
+    /// Implements dumping ATA devices
+    /// </summary>
     public class Ata
     {
+        /// <summary>
+        /// Dumps an ATA device
+        /// </summary>
+        /// <param name="dev">Device</param>
+        /// <param name="devicePath">Path to the device</param>
+        /// <param name="outputPrefix">Prefix for output data files</param>
+        /// <param name="retryPasses">How many times to retry</param>
+        /// <param name="force">Force to continue dump whenever possible</param>
+        /// <param name="dumpRaw">Dump long sectors</param>
+        /// <param name="persistent">Store whatever data the drive returned on error</param>
+        /// <param name="stopOnError">Stop dump on first error</param>
+        /// <param name="resume">Information for dump resuming</param>
+        /// <param name="dumpLog">Dump logger</param>
+        /// <param name="encoding">Encoding to use when analyzing dump</param>
+        /// <exception cref="InvalidOperationException">If the resume file is invalid</exception>
         public static void Dump(Device dev, string devicePath, string outputPrefix, ushort retryPasses, bool force,
                                 bool dumpRaw, bool persistent, bool stopOnError, ref Resume resume,
                                 ref DumpLog dumpLog, Encoding encoding)
@@ -222,7 +240,7 @@ namespace DiscImageChef.Core.Devices.Dumping
                     ResumeSupport.Process(ataReader.IsLba, removable, blocks, dev.Manufacturer, dev.Model, dev.Serial,
                                           dev.PlatformId, ref resume, ref currentTry, ref extents);
                     if(currentTry == null || extents == null)
-                        throw new Exception("Could not process resume file, not continuing...");
+                        throw new InvalidOperationException("Could not process resume file, not continuing...");
 
                     MhddLog mhddLog;
                     IbgLog ibgLog;

DiscImageChef.Core/Devices/Dumping/CompactDisc.cs

@@ -52,8 +52,32 @@ using TrackType = Schemas.TrackType;
 
 namespace DiscImageChef.Core.Devices.Dumping
 {
+    /// <summary>
+    /// Implement dumping Compact Discs
+    /// </summary>
     class CompactDisc
     {
+        /// <summary>
+        /// Dumps a compact disc
+        /// </summary>
+        /// <param name="dev">Device</param>
+        /// <param name="devicePath">Path to the device</param>
+        /// <param name="outputPrefix">Prefix for output data files</param>
+        /// <param name="retryPasses">How many times to retry</param>
+        /// <param name="force">Force to continue dump whenever possible</param>
+        /// <param name="dumpRaw">Dump scrambled sectors</param>
+        /// <param name="persistent">Store whatever data the drive returned on error</param>
+        /// <param name="stopOnError">Stop dump on first error</param>
+        /// <param name="resume">Information for dump resuming</param>
+        /// <param name="dumpLog">Dump logger</param>
+        /// <param name="sidecar">Partially filled initialized sidecar</param>
+        /// <param name="dskType">Disc type as detected in MMC layer</param>
+        /// <param name="separateSubchannel">Write subchannel separate from main channel</param>
+        /// <param name="alcohol">Alcohol disc image already initialized</param>
+        /// <param name="dumpLeadIn">Try to read and dump as much Lead-in as possible</param>
+        /// <exception cref="NotImplementedException">If trying to dump scrambled sectors</exception>
+        /// <exception cref="InvalidOperationException">If the resume file is invalid</exception>
+        /// <exception cref="ArgumentOutOfRangeException">If the track type is unknown (never)</exception>
         internal static void Dump(Device dev, string devicePath, string outputPrefix, ushort retryPasses, bool force,
                                   bool dumpRaw, bool persistent, bool stopOnError, ref CICMMetadataType sidecar,
                                   ref MediaType dskType, bool separateSubchannel, ref Resume resume,
@@ -367,7 +391,7 @@ namespace DiscImageChef.Core.Devices.Dumping
             ResumeSupport.Process(true, true, blocks, dev.Manufacturer, dev.Model, dev.Serial, dev.PlatformId,
                                   ref resume, ref currentTry, ref extents);
             if(currentTry == null || extents == null)
-                throw new Exception("Could not process resume file, not continuing...");
+                throw new InvalidOperationException("Could not process resume file, not continuing...");
 
             if(dumpLeadIn)
             {

DiscImageChef.Core/Devices/Dumping/MMC.cs

@@ -48,8 +48,30 @@ using Spare = DiscImageChef.Decoders.DVD.Spare;
 
 namespace DiscImageChef.Core.Devices.Dumping
 {
+    /// <summary>
+    /// Implement dumping optical discs from MultiMedia devices
+    /// </summary>
     static class Mmc
     {
+        /// <summary>
+        /// Dumps an optical disc
+        /// </summary>
+        /// <param name="dev">Device</param>
+        /// <param name="devicePath">Path to the device</param>
+        /// <param name="outputPrefix">Prefix for output data files</param>
+        /// <param name="retryPasses">How many times to retry</param>
+        /// <param name="force">Force to continue dump whenever possible</param>
+        /// <param name="dumpRaw">Dump raw/long sectors</param>
+        /// <param name="persistent">Store whatever data the drive returned on error</param>
+        /// <param name="stopOnError">Stop dump on first error</param>
+        /// <param name="resume">Information for dump resuming</param>
+        /// <param name="dumpLog">Dump logger</param>
+        /// <param name="encoding">Encoding to use when analyzing dump</param>
+        /// <param name="sidecar">Partially filled initialized sidecar</param>
+        /// <param name="dskType">Disc type as detected in MMC layer</param>
+        /// <param name="separateSubchannel">Write subchannel separate from main channel</param>
+        /// <param name="dumpLeadIn">Try to read and dump as much Lead-in as possible</param>
+        /// <exception cref="NotImplementedException">If trying to dump GOD or WOD, or XGDs without a Kreon drive</exception>
         internal static void Dump(Device dev, string devicePath, string outputPrefix, ushort retryPasses, bool force,
                                   bool dumpRaw, bool persistent, bool stopOnError, ref CICMMetadataType sidecar,
                                   ref MediaType dskType, bool separateSubchannel, ref Resume resume,

DiscImageChef.Core/Devices/Dumping/ResumeSupport.cs

@@ -39,8 +39,26 @@ using PlatformID = DiscImageChef.Interop.PlatformID;
 
 namespace DiscImageChef.Core.Devices.Dumping
 {
+    /// <summary>
+    /// Implements resume support
+    /// </summary>
     static class ResumeSupport
     {
+        /// <summary>
+        /// Process resume
+        /// </summary>
+        /// <param name="isLba">If drive is LBA</param>
+        /// <param name="removable">If media is removable from device</param>
+        /// <param name="blocks">Media blocks</param>
+        /// <param name="manufacturer">Device manufacturer</param>
+        /// <param name="model">Device model</param>
+        /// <param name="serial">Device serial</param>
+        /// <param name="platform">Platform where the dump is made</param>
+        /// <param name="resume">Previous resume, or null</param>
+        /// <param name="currentTry">Current dumping hardware</param>
+        /// <param name="extents">Dumped extents</param>
+        /// <exception cref="NotImplementedException">If device uses CHS addressing</exception>
+        /// <exception cref="InvalidOperationException">If the provided resume does not correspond with the current in progress dump</exception>
         internal static void Process(bool isLba, bool removable, ulong blocks, string manufacturer, string model,
                                    string serial, PlatformID platform, ref Resume resume,
                                    ref DumpHardwareType currentTry, ref ExtentsULong extents)
@@ -51,27 +69,30 @@ namespace DiscImageChef.Core.Devices.Dumping
 
                 if(resume.Removable != removable)
                     throw new
-                        Exception($"Resume file specifies a {(resume.Removable ? "removable" : "non removable")} device but you're requesting to dump a {(removable ? "removable" : "non removable")} device, not continuing...");
+                        InvalidOperationException($"Resume file specifies a {(resume.Removable ? "removable" : "non removable")} device but you're requesting to dump a {(removable ? "removable" : "non removable")} device, not continuing...");
 
                 if(resume.LastBlock != blocks - 1)
                     throw new
-                        Exception($"Resume file specifies a device with {resume.LastBlock + 1} blocks but you're requesting to dump one with {blocks} blocks, not continuing...");
+                        InvalidOperationException($"Resume file specifies a device with {resume.LastBlock + 1} blocks but you're requesting to dump one with {blocks} blocks, not continuing...");
 
                 foreach(DumpHardwareType oldtry in resume.Tries)
                 {
-                    if(oldtry.Manufacturer != manufacturer && !removable)
-                        throw new
-                            Exception($"Resume file specifies a device manufactured by {oldtry.Manufacturer} but you're requesting to dump one by {manufacturer}, not continuing...");
+                    if(!removable)
+                    {
+                        if(oldtry.Manufacturer != manufacturer)
+                            throw new
+                                InvalidOperationException($"Resume file specifies a device manufactured by {oldtry.Manufacturer} but you're requesting to dump one by {manufacturer}, not continuing...");
 
-                    if(oldtry.Model != model && !removable)
-                        throw new
-                            Exception($"Resume file specifies a device model {oldtry.Model} but you're requesting to dump model {model}, not continuing...");
+                        if(oldtry.Model != model)
+                            throw new
+                                InvalidOperationException($"Resume file specifies a device model {oldtry.Model} but you're requesting to dump model {model}, not continuing...");
 
-                    if(oldtry.Serial != serial && !removable)
-                        throw new
-                            Exception($"Resume file specifies a device with serial {oldtry.Serial} but you're requesting to dump one with serial {serial}, not continuing...");
+                        if(oldtry.Serial != serial)
+                            throw new
+                                InvalidOperationException($"Resume file specifies a device with serial {oldtry.Serial} but you're requesting to dump one with serial {serial}, not continuing...");
+                    }
 
-                    if(oldtry.Software == null) throw new Exception("Found corrupt resume file, cannot continue...");
+                    if(oldtry.Software == null) throw new InvalidOperationException("Found corrupt resume file, cannot continue...");
 
                     if(oldtry.Software.Name != "DiscImageChef" ||
                        oldtry.Software.OperatingSystem != platform.ToString() ||

DiscImageChef.Core/Devices/Dumping/SBC.cs

@@ -53,8 +53,30 @@ using TrackType = DiscImageChef.DiscImages.TrackType;
 
 namespace DiscImageChef.Core.Devices.Dumping
 {
+    /// <summary>
+    /// Implements dumping SCSI Block Commands and Reduced Block Commands devices
+    /// </summary>
     static class Sbc
     {
+        /// <summary>
+        /// Dumps a SCSI Block Commands device or a Reduced Block Commands devices
+        /// </summary>
+        /// <param name="dev">Device</param>
+        /// <param name="devicePath">Path to the device</param>
+        /// <param name="outputPrefix">Prefix for output data files</param>
+        /// <param name="retryPasses">How many times to retry</param>
+        /// <param name="force">Force to continue dump whenever possible</param>
+        /// <param name="dumpRaw">Dump long or scrambled sectors</param>
+        /// <param name="persistent">Store whatever data the drive returned on error</param>
+        /// <param name="stopOnError">Stop dump on first error</param>
+        /// <param name="resume">Information for dump resuming</param>
+        /// <param name="dumpLog">Dump logger</param>
+        /// <param name="encoding">Encoding to use when analyzing dump</param>
+        /// <param name="opticalDisc">If device contains an optical disc (e.g. DVD or BD)</param>
+        /// <param name="sidecar">Partially filled initialized sidecar</param>
+        /// <param name="dskType">Disc type as detected in SCSI or MMC layer</param>
+        /// <param name="alcohol">Alcohol disc image already initialized for optical discs, null otherwise</param>
+        /// <exception cref="InvalidOperationException">If the resume file is invalid</exception>
         internal static void Dump(Device dev, string devicePath, string outputPrefix, ushort retryPasses, bool force,
                                   bool dumpRaw, bool persistent, bool stopOnError, ref CICMMetadataType sidecar,
                                   ref MediaType dskType, bool opticalDisc, ref Resume resume,
@@ -336,7 +358,7 @@ namespace DiscImageChef.Core.Devices.Dumping
             ResumeSupport.Process(true, dev.IsRemovable, blocks, dev.Manufacturer, dev.Model, dev.Serial,
                                   dev.PlatformId, ref resume, ref currentTry, ref extents);
             if(currentTry == null || extents == null)
-                throw new Exception("Could not process resume file, not continuing...");
+                throw new InvalidOperationException("Could not process resume file, not continuing...");
 
             dumpFile.Seek(resume.NextBlock, blockSize);
             if(resume.NextBlock > 0) dumpLog.WriteLine("Resuming from block {0}.", resume.NextBlock);

DiscImageChef.Core/Devices/Dumping/SCSI.cs

@@ -43,9 +43,29 @@ using MediaType = DiscImageChef.CommonTypes.MediaType;
 
 namespace DiscImageChef.Core.Devices.Dumping
 {
+    /// <summary>
+    /// Implements dumping SCSI and ATAPI devices
+    /// </summary>
     public class Scsi
     {
         // TODO: Get cartridge serial number from Certance vendor EVPD
+        /// <summary>
+        /// Dumps a SCSI Block Commands device or a Reduced Block Commands devices
+        /// </summary>
+        /// <param name="dev">Device</param>
+        /// <param name="devicePath">Path to the device</param>
+        /// <param name="outputPrefix">Prefix for output data files</param>
+        /// <param name="retryPasses">How many times to retry</param>
+        /// <param name="force">Force to continue dump whenever possible</param>
+        /// <param name="dumpRaw">Dump long or scrambled sectors</param>
+        /// <param name="persistent">Store whatever data the drive returned on error</param>
+        /// <param name="stopOnError">Stop dump on first error</param>
+        /// <param name="resume">Information for dump resuming</param>
+        /// <param name="dumpLog">Dump logger</param>
+        /// <param name="encoding">Encoding to use when analyzing dump</param>
+        /// <param name="separateSubchannel">Write subchannel separate from main channel</param>
+        /// <param name="dumpLeadIn">Try to read and dump as much Lead-in as possible</param>
+        /// <exception cref="ArgumentException">If you asked to dump long sectors from a SCSI Streaming device</exception>
         public static void Dump(Device dev, string devicePath, string outputPrefix, ushort retryPasses, bool force,
                                 bool dumpRaw, bool persistent, bool stopOnError, bool separateSubchannel,
                                 ref Resume resume, ref DumpLog dumpLog, bool dumpLeadIn, Encoding encoding)

DiscImageChef.Core/Devices/Dumping/SSC.cs

@@ -48,6 +48,15 @@ namespace DiscImageChef.Core.Devices.Dumping
 {
     static class Ssc
     {
+        /// <summary>
+        /// Dumps the tape from a SCSI Streaming device
+        /// </summary>
+        /// <param name="dev">Device</param>
+        /// <param name="devicePath">Path to the device</param>
+        /// <param name="outputPrefix">Prefix for output data files</param>
+        /// <param name="resume">Information for dump resuming</param>
+        /// <param name="dumpLog">Dump logger</param>
+        /// <param name="sidecar">Partially filled initialized sidecar</param>
         internal static void Dump(Device dev, string outputPrefix, string devicePath, ref CICMMetadataType sidecar,
                                   ref Resume resume, ref DumpLog dumpLog)
         {

DiscImageChef.Core/Devices/Dumping/SecureDigital.cs

@@ -50,8 +50,26 @@ using MediaType = DiscImageChef.Metadata.MediaType;
 
 namespace DiscImageChef.Core.Devices.Dumping
 {
+    /// <summary>
+    /// Implements dumping a MultiMediaCard or SecureDigital flash card
+    /// </summary>
     public class SecureDigital
     {
+        /// <summary>
+        /// Dumps a MultiMediaCard or SecureDigital flash card
+        /// </summary>
+        /// <param name="dev">Device</param>
+        /// <param name="devicePath">Path to the device</param>
+        /// <param name="outputPrefix">Prefix for output data files</param>
+        /// <param name="retryPasses">How many times to retry</param>
+        /// <param name="force">Force to continue dump whenever possible</param>
+        /// <param name="dumpRaw">Dump long or scrambled sectors</param>
+        /// <param name="persistent">Store whatever data the drive returned on error</param>
+        /// <param name="stopOnError">Stop dump on first error</param>
+        /// <param name="resume">Information for dump resuming</param>
+        /// <param name="dumpLog">Dump logger</param>
+        /// <param name="encoding">Encoding to use when analyzing dump</param>
+        /// <exception cref="ArgumentException">If you asked to dump long sectors from a SCSI Streaming device</exception>
         public static void Dump(Device dev, string devicePath, string outputPrefix, ushort retryPasses, bool force,
                                 bool dumpRaw, bool persistent, bool stopOnError, ref Resume resume,
                                 ref DumpLog dumpLog, Encoding encoding)
@@ -280,7 +298,7 @@ namespace DiscImageChef.Core.Devices.Dumping
             ResumeSupport.Process(true, false, blocks, dev.Manufacturer, dev.Model, dev.Serial, dev.PlatformId,
                                   ref resume, ref currentTry, ref extents);
             if(currentTry == null || extents == null)
-                throw new Exception("Could not process resume file, not continuing...");
+                throw new InvalidOperationException("Could not process resume file, not continuing...");
 
             DicConsole.WriteLine("Reading {0} sectors at a time.", blocksToRead);
 

DiscImageChef.Core/Devices/Dumping/XGD.cs

@@ -53,8 +53,28 @@ using TrackType = Schemas.TrackType;
 
 namespace DiscImageChef.Core.Devices.Dumping
 {
+    /// <summary>
+    /// Implements dumping an Xbox Game Disc using a Kreon drive 
+    /// </summary>
     static class Xgd
     {
+        /// <summary>
+        /// Dumps an Xbox Game Disc using a Kreon drive 
+        /// </summary>
+        /// <param name="dev">Device</param>
+        /// <param name="devicePath">Path to the device</param>
+        /// <param name="outputPrefix">Prefix for output data files</param>
+        /// <param name="retryPasses">How many times to retry</param>
+        /// <param name="force">Force to continue dump whenever possible</param>
+        /// <param name="dumpRaw">Dump raw/long sectors</param>
+        /// <param name="persistent">Store whatever data the drive returned on error</param>
+        /// <param name="stopOnError">Stop dump on first error</param>
+        /// <param name="resume">Information for dump resuming</param>
+        /// <param name="dumpLog">Dump logger</param>
+        /// <param name="encoding">Encoding to use when analyzing dump</param>
+        /// <param name="sidecar">Partially filled initialized sidecar</param>
+        /// <param name="dskType">Disc type as detected in MMC layer</param>
+        /// <exception cref="InvalidOperationException">If the provided resume does not correspond with the current in progress dump</exception>
         internal static void Dump(Device dev, string devicePath, string outputPrefix, ushort retryPasses, bool force,
                                   bool dumpRaw, bool persistent, bool stopOnError, ref CICMMetadataType sidecar,
                                   ref MediaType dskType, ref Resume resume, ref DumpLog dumpLog,
@@ -334,7 +354,7 @@ namespace DiscImageChef.Core.Devices.Dumping
             ResumeSupport.Process(true, true, totalSize, dev.Manufacturer, dev.Model, dev.Serial, dev.PlatformId,
                                   ref resume, ref currentTry, ref extents);
             if(currentTry == null || extents == null)
-                throw new Exception("Could not process resume file, not continuing...");
+                throw new NotImplementedException("Could not process resume file, not continuing...");
 
             ulong currentSector = resume.NextBlock;
             dumpFile.Seek(resume.NextBlock, BLOCK_SIZE);