Improve exception docs in BizHawk.Emulation.Common

BizHawk.Emulation.Common/Base Implementations/BasicServiceProvider.cs

@@ -43,10 +43,9 @@ namespace BizHawk.Emulation.Common
 			}
 		}
 
-		/// <summary>
-		/// the core can call this to register an additional service
-		/// </summary>
-		/// <typeparam name="T">The <seealso cref="IEmulatorService"/> to register</typeparam>
+		/// <summary>the core can call this to register an additional service</summary>
+		/// <typeparam name="T">The <see cref="IEmulatorService"/> to register</typeparam>
+		/// <exception cref="ArgumentNullException"><paramref name="provider"/> is null</exception>
 		public void Register<T>(T provider) 
 			where T : IEmulatorService
 		{

BizHawk.Emulation.Common/Base Implementations/CallbackBasedTraceBuffer.cs

@@ -18,6 +18,7 @@ namespace BizHawk.Emulation.Common
 	/// <seealso cref="IDisassemblable"/> 
 	public abstract class CallbackBasedTraceBuffer : ITraceable
 	{
+		/// <exception cref="InvalidOperationException"><paramref name="debuggableCore"/> does not provide memory callback support or does not implement <see cref="IDebuggable.GetCpuFlagsAndRegisters"/></exception>
 		protected CallbackBasedTraceBuffer(IDebuggable debuggableCore, IMemoryDomains memoryDomains, IDisassemblable disassembler)
 		{
 			if (!debuggableCore.MemoryCallbacksAvailable())

BizHawk.Emulation.Common/Base Implementations/CodeDataLog.cs

@@ -17,9 +17,8 @@ namespace BizHawk.Emulation.Common
 			Active = true;
 		}
 
-		/// <summary>
-		/// Pins the managed arrays. Not that we expect them to be allocated, but in case we do, seeing thish ere will remind us to check for the pin condition and abort
-		/// </summary>
+		/// <summary>Pins the managed arrays. Not that we expect them to be allocated, but in case we do, seeing this here will remind us to check for the pin condition and abort</summary>
+		/// <exception cref="InvalidOperationException">if called more than once per instantiation</exception>
 		public void Pin()
 		{
 			if (_pins.Count != 0)
@@ -112,6 +111,10 @@ namespace BizHawk.Emulation.Common
 			return true;
 		}
 
+		/// <exception cref="InvalidDataException">
+		/// <paramref name="other"/> is not the same length as <see langword="this"/>, or
+		/// any value differs in size from the corresponding value in <paramref name="other"/>
+		/// </exception>
 		public void LogicalOrFrom(ICodeDataLog other)
 		{
 			if (Count != other.Count)
@@ -187,6 +190,7 @@ namespace BizHawk.Emulation.Common
 			return SaveInternal(new MemoryStream(), false);
 		}
 
+		/// <exception cref="InvalidDataException">contents of <paramref name="s"/> do not begin with valid file header</exception>
 		public void Load(Stream s)
 		{
 			var br = new BinaryReader(s);

BizHawk.Emulation.Common/Base Implementations/ControllerDefinition.cs

@@ -122,7 +122,8 @@ namespace BizHawk.Emulation.Common
 				Max = max;
 			}
 
-			// for terse construction
+			/// <summary>for terse construction</summary>
+			/// <exception cref="ArgumentException">length <paramref name="f"/> is not <c>3</c></exception>
 			public static implicit operator FloatRange(float[] f)
 			{
 				if (f.Length != 3)

BizHawk.Emulation.Common/Base Implementations/MemoryCallbackSystem.cs

@@ -39,6 +39,7 @@ namespace BizHawk.Emulation.Common
 
 		public string[] AvailableScopes { get; }
 
+		/// <exception cref="InvalidOperationException">scope of <paramref name="callback"/> isn't available</exception>
 		public void Add(IMemoryCallback callback)
 		{
 			if (!AvailableScopes.Contains(callback.Scope))

BizHawk.Emulation.Common/Base Implementations/NullSound.cs

@@ -44,6 +44,7 @@ namespace BizHawk.Emulation.Common
 
 		public SyncSoundMode SyncMode { get; private set; }
 
+		/// <exception cref="InvalidOperationException"><see cref="SyncMode"/> is not <see cref="SyncSoundMode.Sync"/> (call <see cref="SetSyncMode"/>)</exception>
 		public void GetSamplesSync(out short[] samples, out int nsamp)
 		{
 			if (SyncMode != SyncSoundMode.Sync)
@@ -72,6 +73,7 @@ namespace BizHawk.Emulation.Common
 			SyncMode = mode;
 		}
 
+		/// <exception cref="InvalidOperationException"><see cref="SyncMode"/> is not <see cref="SyncSoundMode.Async"/> (call <see cref="SetSyncMode"/>)</exception>
 		public void GetSamplesAsync(short[] samples)
 		{
 			if (SyncMode != SyncSoundMode.Async)

BizHawk.Emulation.Common/Base Implementations/SimpleSyncSoundProvider.cs

@@ -12,6 +12,7 @@ namespace BizHawk.Emulation.Common.Base_Implementations
 
 		public bool CanProvideAsync => false;
 
+		/// <exception cref="ArgumentException"><paramref name="mode"/> is not <see cref="SyncSoundMode.Sync"/></exception>
 		public void SetSyncMode(SyncSoundMode mode)
 		{
 			if (mode != SyncSoundMode.Sync)
@@ -48,6 +49,7 @@ namespace BizHawk.Emulation.Common.Base_Implementations
 			_nsamp = 0;
 		}
 
+		/// <exception cref="NotImplementedException">always</exception>
 		public void GetSamplesAsync(short[] samples)
 		{
 			throw new NotImplementedException();

BizHawk.Emulation.Common/ControllerDefinitionMerger.cs

@@ -76,6 +76,7 @@ namespace BizHawk.Emulation.Common
 				_remaps = remaps;
 			}
 
+			/// <exception cref="NotImplementedException">always</exception>
 			public ControllerDefinition Definition => throw new NotImplementedException();
 
 			public bool IsPressed(string button)

BizHawk.Emulation.Common/Interfaces/IMemoryCallbackSystem.cs

@@ -60,7 +60,7 @@ namespace BizHawk.Emulation.Common
 		/// If no address is specified the callback will be hooked to all addresses
 		/// Note: an execute callback can not be added without an address, else an InvalidOperationException will occur
 		/// </summary>
-		/// <exception cref="InvalidCastException">Thrown when the <see cref="IMemoryCallback.Scope"/> property of the <see cref="IMemoryCallback"/> is not in the <see cref="AvailableScopes"/></exception>
+		/// <exception cref="InvalidOperationException">Thrown when the <see cref="IMemoryCallback.Scope"/> property of the <see cref="IMemoryCallback"/> is not in the <see cref="AvailableScopes"/></exception>
 		void Add(IMemoryCallback callback);
 
 		/// <summary>

BizHawk.Emulation.Common/Interfaces/Services/IDebuggable.cs

@@ -49,6 +49,7 @@ namespace BizHawk.Emulation.Common
 		public ulong Value { get; }
 		public byte BitSize { get; }
 
+		/// <exception cref="ArgumentOutOfRangeException"><paramref name="bitSize"/> not in 1..64</exception>
 		public RegisterValue(ulong val, byte bitSize)
 		{
 			if (bitSize == 64)

BizHawk.Emulation.Common/Interfaces/Services/IDisassemblable.cs

@@ -40,6 +40,7 @@ namespace BizHawk.Emulation.Common
 	{
 		private string _cpu;
 
+		/// <exception cref="ArgumentException">(from setter) <paramref name="value"/> isn't the name of an available CPU</exception>
 		public virtual string Cpu
 		{
 			get => _cpu;

BizHawk.Emulation.Common/Interfaces/Services/ISettable.cs

@@ -103,6 +103,7 @@ namespace BizHawk.Emulation.Common
 		private readonly MethodInfo _getss;
 		private readonly MethodInfo _putss;
 
+		/// <exception cref="InvalidOperationException">does not have non-sync settings</exception>
 		public object GetSettings()
 		{
 			if (!HasSettings)
@@ -113,6 +114,7 @@ namespace BizHawk.Emulation.Common
 			return _gets.Invoke(_emu, _tmp0);
 		}
 
+		/// <exception cref="InvalidOperationException">does not have sync settings</exception>
 		public object GetSyncSettings()
 		{
 			if (!HasSyncSettings)
@@ -123,6 +125,7 @@ namespace BizHawk.Emulation.Common
 			return _getss.Invoke(_emu, _tmp0);
 		}
 
+		/// <exception cref="InvalidOperationException">does not have non-sync settings</exception>
 		public bool PutSettings(object o)
 		{
 			if (!HasSettings)
@@ -134,6 +137,7 @@ namespace BizHawk.Emulation.Common
 			return (bool)_puts.Invoke(_emu, _tmp1);
 		}
 
+		/// <exception cref="InvalidOperationException">does not have sync settings</exception>
 		public bool PutSyncSettings(object o)
 		{
 			if (!HasSyncSettings)

BizHawk.Emulation.Common/Interfaces/Services/ISoundProvider.cs

@@ -25,6 +25,7 @@
 		/// If a core can not provide async sound and the mode is set to sync,
 		/// an NotSupportedException should be thrown
 		/// </summary>
+		/// <exception cref="NotSupportedException"></exception>
 		void SetSyncMode(SyncSoundMode mode);
 
 		/// <summary>
@@ -36,12 +37,14 @@
 		/// Provides samples in sync mode
 		/// If the core is not in sync mode, this should throw an InvalidOperationException
 		/// </summary>
+		/// <exception cref="InvalidOperationException"></exception>
 		void GetSamplesSync(out short[] samples, out int nsamp);
 
 		/// <summary>
 		/// Provides samples in async mode
 		/// If the core is not in async mode, this should throw an InvalidOperationException
 		/// </summary>
+		/// <exception cref="InvalidOperationException"></exception>
 		void GetSamplesAsync(short[] samples);
 
 		/// <summary>

BizHawk.Emulation.Common/SaveController.cs

@@ -54,9 +54,8 @@ namespace BizHawk.Emulation.Common
 			}
 		}
 
-		/// <summary>
-		/// This controller's definition changes to that of source
-		/// </summary>
+		/// <summary>replace this controller's definition with that of <paramref name="source"/></summary>
+		/// <exception cref="Exception">definition of <paramref name="source"/> has a button and an analog control with the same name</exception>
 		public void CopyFrom(IController source)
 		{
 			Definition = source.Definition;

BizHawk.Emulation.Common/Sound/Utilities/BlipBuffer.cs

@@ -77,6 +77,7 @@ namespace BizHawk.Emulation.Common
 
 		private IntPtr _context;
 
+		/// <exception cref="Exception">unmanaged call failed</exception>
 		public BlipBuffer(int sampleCount)
 		{
 			_context = BlipBufDll.blip_new(sampleCount);
@@ -140,6 +141,7 @@ namespace BizHawk.Emulation.Common
 			return BlipBufDll.blip_samples_avail(_context);
 		}
 
+		/// <exception cref="ArgumentOutOfRangeException"><paramref name="output"/> can't hold <paramref name="count"/> samples (or twice that if <paramref name="stereo"/> is <see langword="true"/>)</exception>
 		public int ReadSamples(short[] output, int count, bool stereo)
 		{
 			if (output.Length < count * (stereo ? 2 : 1))
@@ -150,6 +152,7 @@ namespace BizHawk.Emulation.Common
 			return BlipBufDll.blip_read_samples(_context, output, count, stereo ? 1 : 0);
 		}
 
+		/// <exception cref="ArgumentOutOfRangeException"><paramref name="output"/> can't hold 2 * <paramref name="count"/> samples</exception>
 		public int ReadSamplesLeft(short[] output, int count)
 		{
 			if (output.Length < count * 2)
@@ -160,6 +163,7 @@ namespace BizHawk.Emulation.Common
 			return BlipBufDll.blip_read_samples(_context, output, count, 1);
 		}
 
+		/// <exception cref="ArgumentOutOfRangeException"><paramref name="output"/> can't hold 2 * <paramref name="count"/> samples</exception>
 		public int ReadSamplesRight(short[] output, int count)
 		{
 			if (output.Length < count * 2)

BizHawk.Emulation.Common/Sound/Utilities/DCFilter.cs

@@ -27,6 +27,8 @@ namespace BizHawk.Emulation.Common
 			return ret;
 		}
 
+		/// <exception cref="ArgumentNullException"><paramref name="input"/> is null</exception>
+		/// <exception cref="ArgumentOutOfRangeException"><paramref name="filterWidth"/> is not in 8..65536</exception>
 		public DCFilter(ISoundProvider input, int filterWidth)
 		{
 			if (input == null)
@@ -44,7 +46,8 @@ namespace BizHawk.Emulation.Common
 			_soundProvider = input;
 		}
 
-		// Detached mode
+		/// <summary>detached mode</summary>
+		/// <exception cref="ArgumentOutOfRangeException"><paramref name="filterWidth"/> is not in 8..65536</exception>
 		public DCFilter(int filterWidth)
 		{
 			if (filterWidth < 8 || filterWidth > 65536)

BizHawk.Emulation.Common/Sound/Utilities/Metaspu.cs

@@ -54,6 +54,7 @@ namespace BizHawk.Emulation.Common
 
 		public SyncSoundMode SyncMode => SyncSoundMode.Async;
 
+		/// <exception cref="NotSupportedException"><paramref name="mode"/> is not <see cref="SyncSoundMode.Async"/></exception>
 		public void SetSyncMode(SyncSoundMode mode)
 		{
 			if (mode != SyncSoundMode.Async)
@@ -62,6 +63,7 @@ namespace BizHawk.Emulation.Common
 			}
 		}
 
+		/// <exception cref="InvalidOperationException">always</exception>
 		public void GetSamplesSync(out short[] samples, out int nsamp)
 		{
 			throw new InvalidOperationException("Sync mode not supported");

BizHawk.Emulation.Common/Sound/Utilities/SpeexResampler.cs

@@ -288,9 +288,6 @@ namespace BizHawk.Emulation.Common
 			}
 		}
 
-		/// <summary>
-		/// Initializes a new instance of the <see cref="SpeexResampler"/> class
-		/// </summary>
 		/// <param name="quality">0 to 10</param>
 		/// <param name="rationum">numerator of sample rate change ratio (inrate / outrate)</param>
 		/// <param name="ratioden">denominator of sample rate change ratio (inrate / outrate)</param>
@@ -298,6 +295,8 @@ namespace BizHawk.Emulation.Common
 		/// <param name="srateout">sampling rate out, rounded to nearest hz</param>
 		/// <param name="drainer">function which accepts output as produced. if null, act as an <seealso cref="ISoundProvider"/></param>
 		/// <param name="input">source to take input from when output is requested. if null, no auto-fetching</param>
+		/// <exception cref="ArgumentException"><paramref name="drainer"/> and <paramref name="input"/> are both non-null</exception>
+		/// <exception cref="Exception">unmanaged call failed</exception>
 		public SpeexResampler(Quality quality, uint rationum, uint ratioden, uint sratein, uint srateout, Action<short[], int> drainer = null, ISoundProvider input = null)
 		{
 			if (drainer != null && input != null)
@@ -369,9 +368,8 @@ namespace BizHawk.Emulation.Common
 			}
 		}
 
-		/// <summary>
-		/// flush as many input samples as possible, generating output samples right now
-		/// </summary>
+		/// <summary>flush as many input samples as possible, generating output samples right now</summary>
+		/// <exception cref="Exception">unmanaged call failed</exception>
 		public void Flush()
 		{
 			uint inal = (uint)_inbufpos / 2;
@@ -448,11 +446,13 @@ namespace BizHawk.Emulation.Common
 
 		public SyncSoundMode SyncMode => SyncSoundMode.Sync;
 
+		/// <exception cref="InvalidOperationException">always</exception>
 		public void GetSamplesAsync(short[] samples)
 		{
 			throw new InvalidOperationException("Async mode is not supported.");
 		}
 
+		/// <exception cref="NotSupportedException"><paramref name="mode"/> is <see cref="SyncSoundMode.Async"/></exception>
 		public void SetSyncMode(SyncSoundMode mode)
 		{
 			if (mode == SyncSoundMode.Async)

BizHawk.Emulation.Common/TextState.cs

@@ -55,6 +55,7 @@ namespace BizHawk.Emulation.Common
 			Current.Data.Add(name, d); // will except for us if the key is already present
 		}
 
+		/// <exception cref="InvalidOperationException"><paramref name="length"/> does not match the length of the data saved as <paramref name="name"/></exception>
 		public void Load(IntPtr data, int length, string name)
 		{
 			byte[] d = Current.Data[name];
@@ -93,6 +94,7 @@ namespace BizHawk.Emulation.Common
 			Nodes.Push(next);
 		}
 
+		/// <exception cref="InvalidOperationException"><paramref name="name"/> doesn't match the section being closed</exception>
 		public void ExitSection(string name)
 		{
 			Node last = Nodes.Pop();