Improve exception docs in BizHawk.Emulation.DiscSystem

BizHawk.Emulation.DiscSystem/API_MednaDisc.cs

@@ -16,6 +16,7 @@ namespace BizHawk.Emulation.DiscSystem
 	/// </summary>
 	public unsafe class MednaDisc : IDisposable
 	{
+		/// <exception cref="InvalidOperationException"><see cref="IsLibraryAvailable"/> is <see langword="false"/> (could not load <c>mednadisc.dll</c>), or unmanaged call failed</exception>
 		public MednaDisc(string pathToDisc)
 		{
 			if (!IsLibraryAvailable)

BizHawk.Emulation.DiscSystem/DiscDecoding.cs

@@ -85,6 +85,7 @@ namespace BizHawk.Emulation.DiscSystem
 			};
 		}
 
+		/// <exception cref="InvalidOperationException">FFmpeg exited with non-zero exit code or produced no output</exception>
 		public byte[] DecodeAudio(string path)
 		{
 			string tempfile = Path.GetTempFileName();
@@ -158,6 +159,7 @@ namespace BizHawk.Emulation.DiscSystem
 			return null;
 		}
 
+		/// <exception cref="AudioDecoder_Exception">could not find source audio for <paramref name="audioPath"/></exception>
 		public byte[] AcquireWaveData(string audioPath)
 		{
 			string path = FindAudio(audioPath);

BizHawk.Emulation.DiscSystem/DiscFormats/Blobs/Blob_WaveFile.cs

@@ -84,6 +84,7 @@ namespace BizHawk.Emulation.DiscSystem
 				Load(stream);
 			}
 
+			/// <exception cref="Blob_WaveFile_Exception">not a valid RIFF WAVE file with exactly one data chunk containing two 16-bit PCM channels at 44.1 kHz</exception>
 			public void Load(Stream stream)
 			{
 				try

BizHawk.Emulation.DiscSystem/DiscFormats/Blobs/RiffMaster.cs

@@ -234,6 +234,8 @@ namespace BizHawk.Emulation.DiscSystem
 		{
 			public Dictionary<string, string> dictionary = new Dictionary<string, string>();
 			public RiffContainer_INFO() { type = "INFO"; }
+
+			/// <exception cref="FormatException"><paramref name="rc"/>.<see cref="RiffContainer.subchunks"/> contains a chunk that does not inherit <see cref="RiffSubchunk"/></exception>
 			public RiffContainer_INFO(RiffContainer rc)
 			{
 				subchunks = rc.subchunks;
@@ -327,9 +329,8 @@ namespace BizHawk.Emulation.DiscSystem
 			riff.WriteStream(s);
 		}
 
-		/// <summary>
+		/// <summary>takes posession of the supplied stream</summary>
-		/// takes posession of the supplied stream
+		/// <exception cref="FormatException"><paramref name="s"/> does not contain a riff chunk</exception>
-		/// </summary>
 		public void LoadStream(Stream s)
 		{
 			Dispose();

BizHawk.Emulation.DiscSystem/DiscFormats/CCD_format.cs

@@ -167,6 +167,8 @@ namespace BizHawk.Emulation.DiscSystem
 				TryGetValue(key, out def);
 				return def;
 			}
+
+			/// <exception cref="CCDParseException"><paramref name="key"/> not found in <see langword="this"/></exception>
 			public int FetchOrFail(string key)
 			{
 				int ret;
@@ -234,9 +236,7 @@ namespace BizHawk.Emulation.DiscSystem
 			return version;
 		}
 
-		/// <summary>
+		/// <exception cref="CCDParseException">parsed <see cref="CCDFile.DataTracksScrambled"/> is <c>1</c>, parsed session number is not <c>1</c>, or malformed entry</exception>
-		/// Parses a CCD file contained in the provided stream
-		/// </summary>
 		public CCDFile ParseFrom(Stream stream)
 		{
 			CCDFile ccdf = new CCDFile();
@@ -322,7 +322,7 @@ namespace BizHawk.Emulation.DiscSystem
 			public List<RawTOCEntry> RawTOCEntries;
 			public CCDFile ParsedCCDFile;
 			public bool Valid;
-			public Exception FailureException;
+			public CCDParseException FailureException;
 			public string ImgPath;
 			public string SubPath;
 			public string CcdPath;
@@ -471,10 +471,7 @@ namespace BizHawk.Emulation.DiscSystem
 			}
 		}
 
-
+		/// <exception cref="CCDParseException">file <paramref name="ccdPath"/> not found, nonexistent IMG file, nonexistent SUB file, IMG or SUB file not multiple of <c>2352 B</c>, or IMG and SUB files differ in length</exception>
-		/// <summary>
-		/// Loads a CCD at the specified path to a Disc object
-		/// </summary>
 		public Disc LoadCCDToDisc(string ccdPath, DiscMountPolicy IN_DiscMountPolicy)
 		{
 			var loadResults = LoadCCDPath(ccdPath);

BizHawk.Emulation.DiscSystem/DiscFormats/MDS_Format.cs

@@ -289,6 +289,7 @@ namespace BizHawk.Emulation.DiscSystem
 			public int BlobIndex;
 		}
 
+		/// <exception cref="MDSParseException">header is malformed or identifies file as MDS 2.x, or any track has a DVD mode</exception>
 		public AFile Parse(Stream stream)
 		{
 			EndianBitConverter bc = EndianBitConverter.CreateForLittleEndian();
@@ -580,7 +581,7 @@ namespace BizHawk.Emulation.DiscSystem
 			public List<RawTOCEntry> RawTOCEntries;
 			public AFile ParsedMDSFile;
 			public bool Valid;
-			public Exception FailureException;
+			public MDSParseException FailureException;
 			public string MdsPath;
 		}
 
@@ -609,6 +610,7 @@ namespace BizHawk.Emulation.DiscSystem
 			return ret;
 		}
 
+		/// <exception cref="MDSParseException">path reference no longer points to file</exception>
 		Dictionary<int, IBlob> MountBlobs(AFile mdsf, Disc disc)
 		{
 			Dictionary<int, IBlob> BlobIndex = new Dictionary<int, IBlob>();
@@ -690,10 +692,7 @@ namespace BizHawk.Emulation.DiscSystem
 			return new RawTOCEntry { QData = q };
 		}
 
-
+		/// <exception cref="MDSParseException">no file found at <paramref name="mdsPath"/> or BLOB error</exception>
-		/// <summary>
-		/// Loads a MDS at the specified path to a Disc object
-		/// </summary>
 		public Disc LoadMDSToDisc(string mdsPath, DiscMountPolicy IN_DiscMountPolicy)
 		{
 			var loadResults = LoadMDSPath(mdsPath);

BizHawk.Emulation.DiscSystem/DiscHasher.cs

@@ -123,6 +123,11 @@ namespace BizHawk.Emulation.DiscSystem
 			}
 
 			uint current = 0xFFFFFFFF;
+
+			/// <exception cref="ArgumentOutOfRangeException">
+			/// <paramref name="offset"/> is negative, or
+			/// end index (<paramref name="offset"/> + <paramref name="size"/>) is beyond the end of <paramref name="data"/>
+			/// </exception>
 			public unsafe void Add(byte[] data, int offset, int size)
 			{
 				if (offset + size > data.Length)

BizHawk.Emulation.DiscSystem/DiscMountJob.cs

@@ -47,6 +47,7 @@ namespace BizHawk.Emulation.DiscSystem
 		/// </summary>
 		public bool OUT_SlowLoadAborted;
 
+		/// <exception cref="NotSupportedException"><see cref="IN_DiscInterface"/> is <see cref="DiscInterface.LibMirage"/></exception>
 		public void Run()
 		{
 			switch (IN_DiscInterface)

BizHawk.Emulation.DiscSystem/DiscSectorReader.cs

@@ -196,6 +196,7 @@ namespace BizHawk.Emulation.DiscSystem
 		/// If any console is trying to do that, we'll have to add a policy for it, or handle it in the console.
 		/// (We can add a method to this API that checks the type of a sector to make that easier)
 		/// </summary>
+		/// <exception cref="InvalidOperationException"></exception>
 		public int ReadLBA_2048(int lba, byte[] buffer, int offset)
 		{
 			if (Policy.UserData2048Mode == DiscSectorReaderPolicy.EUserData2048Mode.AssumeMode1)

BizHawk.Emulation.DiscSystem/DiscStream.cs

@@ -63,6 +63,7 @@ namespace BizHawk.Emulation.DiscSystem
 		int cachedSector;
 		DiscSectorReader dsr;
 
+		/// <exception cref="NotSupportedException"><paramref name="view"/> is not <see cref="DiscSectorReaderPolicy.EUserData2048Mode.AssumeMode1"/> or <see cref="DiscSectorReaderPolicy.EUserData2048Mode.AssumeMode2_Form1"/></exception>
 		public DiscStream(Disc disc, EDiscStreamView view, int from_lba)
 		{
 			SectorSize = 2048;

BizHawk.Emulation.DiscSystem/Internal/Jobs/LoadSBIJob.cs

@@ -22,6 +22,7 @@ namespace BizHawk.Emulation.DiscSystem.SBI
 		/// </summary>
 		public SubQPatchData OUT_Data;
 
+		/// <exception cref="SBIParseException">file at <see cref="IN_Path"/> does not contain valid header or contains misformatted record</exception>
 		public void Run()
 		{
 			using (var fs = File.OpenRead(IN_Path))

BizHawk.Emulation.DiscSystem/Internal/Jobs/Synthesize_A0A1A2_Job.cs

@@ -34,9 +34,8 @@ namespace BizHawk.Emulation.DiscSystem
 		/// </summary>
 		public SessionFormat IN_Session1Format;
 
-		/// <summary>
+		/// <summary>appends the new entries to the provided list</summary>
-		/// Appends the new entries to the provided list
+		/// <exception cref="InvalidOperationException"><see cref="IN_Session1Format"/> is <see cref="SessionFormat.None"/> or a non-member</exception>
-		/// </summary>
 		public void Run(List<RawTOCEntry> entries)
 		{
 			//NOTE: entries are inserted at the beginning due to observations of CCD indicating they might need to be that way

BizHawk.Emulation.DiscSystem/Internal/Jobs/Synthesize_DiscStructure_From_DiscTOC_Job.cs

@@ -9,6 +9,7 @@ namespace BizHawk.Emulation.DiscSystem
 		public DiscTOC TOCRaw;
 		public DiscStructure Result;
 
+		/// <exception cref="InvalidOperationException">first track of <see cref="TOCRaw"/> is not <c>1</c></exception>
 		public void Run()
 		{
 			var dsr = new DiscSectorReader(IN_Disc);