Improve exception docs in BizHawk.Client.Common

BizHawk.Client.Common/Api/Classes/MemApi.cs

@@ -190,6 +190,7 @@ namespace BizHawk.Client.Common
 			return false;
 		}
 
+		/// <exception cref="ArgumentOutOfRangeException">range defined by <paramref name="addr"/> and <paramref name="count"/> extends beyond the bound of <paramref name="domain"/> (or <see cref="Domain"/> if null)</exception>
 		public string HashRegion(long addr, int count, string domain = null)
 		{
 			var d = NamedDomainOrCurrent(domain);

BizHawk.Client.Common/Api/Classes/UserDataApi.cs

@@ -4,6 +4,7 @@ namespace BizHawk.Client.Common
 {
 	public sealed class UserDataApi : IUserData
 	{
+		/// <exception cref="InvalidOperationException">type of <paramref name="value"/> cannot be used in userdata</exception>
 		public void Set(string name, object value)
 		{
 			if (value != null)

BizHawk.Client.Common/BinarySaveStates.cs

@@ -235,13 +235,11 @@ namespace BizHawk.Client.Common
 			}
 		}
 
-		/// <summary>
-		/// Gets a lump
-		/// </summary>
-		/// <param name="lump">lump to retriever</param>
-		/// <param name="abort">true to throw exception on failure</param>
+		/// <param name="lump">lump to retrieve</param>
+		/// <param name="abort">pass true to throw exception instead of returning false</param>
 		/// <param name="callback">function to call with the desired stream</param>
-		/// <returns>true if callback was called and stream was loaded</returns>
+		/// <returns>true iff stream was loaded</returns>
+		/// <exception cref="Exception">stream not found and <paramref name="abort"/> is <see langword="true"/></exception>
 		public bool GetLump(BinaryStateLump lump, bool abort, Action<Stream, long> callback)
 		{
 			ZipEntry e;
@@ -290,6 +288,7 @@ namespace BizHawk.Client.Common
 			});
 		}
 
+		/// <exception cref="Exception">couldn't find Binary or Text savestate</exception>
 		public void GetCoreState(Action<BinaryReader, long> callbackBinary, Action<TextReader> callbackText)
 		{
 			if (!GetLump(BinaryStateLump.Corestate, false, callbackBinary)
@@ -299,6 +298,7 @@ namespace BizHawk.Client.Common
 			}
 		}
 
+		/// <exception cref="Exception">couldn't find Binary or Text savestate</exception>
 		public void GetCoreState(Action<BinaryReader> callbackBinary, Action<TextReader> callbackText)
 		{
 			if (!GetLump(BinaryStateLump.Corestate, false, callbackBinary)

BizHawk.Client.Common/ControllerBinding.cs

@@ -265,6 +265,7 @@ namespace BizHawk.Client.Common
 			_buttonStarts.Clear();
 		}
 
+		/// <exception cref="NotImplementedException">always</exception>
 		public float GetFloat(string name)
 		{
 			throw new NotImplementedException();

BizHawk.Client.Common/CoreFileProvider.cs

@@ -59,6 +59,7 @@ namespace BizHawk.Client.Common
 			}
 		}
 
+		/// <exception cref="MissingFirmwareException">not found and <paramref name="required"/> is true</exception>
 		public string GetFirmwarePath(string sysId, string firmwareId, bool required, string msg = null)
 		{
 			var path = FirmwareManager.Request(sysId, firmwareId);
@@ -99,12 +100,14 @@ namespace BizHawk.Client.Common
 			return ret;
 		}
 
+		/// <exception cref="MissingFirmwareException">not found and <paramref name="required"/> is true</exception>
 		public byte[] GetFirmware(string sysId, string firmwareId, bool required, string msg = null)
 		{
 			string unused;
 			return GetFirmwareWithPath(sysId, firmwareId, required, msg, out unused);
 		}
 
+		/// <exception cref="MissingFirmwareException">not found and <paramref name="required"/> is true</exception>
 		public byte[] GetFirmwareWithGameInfo(string sysId, string firmwareId, bool required, out GameInfo gi, string msg = null)
 		{
 			byte[] ret = GetFirmwareWithPath(sysId, firmwareId, required, msg, out var path);

BizHawk.Client.Common/FrameworkFastZipWriter.cs

@@ -130,6 +130,7 @@ namespace BizHawk.Client.Common
 			}
 		}
 
+		/// <exception cref="NotImplementedException"><paramref name="compressionlevel"/> is <c>0</c></exception>
 		public FrameworkFastZipWriter(string path, int compressionlevel)
 		{
 			_output = new FileStream(path, FileMode.Create, FileAccess.Write);

BizHawk.Client.Common/QuickBmpFile.cs

@@ -29,6 +29,7 @@ namespace BizHawk.Client.Common
 				bfSize = (uint)Marshal.SizeOf(this);
 			}
 
+			/// <exception cref="InvalidOperationException">misformatted data</exception>
 			public static BITMAPFILEHEADER FromStream(Stream s)
 			{
 				var ret = GetObject<BITMAPFILEHEADER>(s);
@@ -62,6 +63,7 @@ namespace BizHawk.Client.Common
 				biSize = (uint)Marshal.SizeOf(this);
 			}
 
+			/// <exception cref="InvalidOperationException">misformatted data</exception>
 			public static BITMAPINFOHEADER FromStream(Stream s)
 			{
 				var ret = GetObject<BITMAPINFOHEADER>(s);
@@ -231,11 +233,13 @@ namespace BizHawk.Client.Common
 			public int BufferHeight { get; set; }
 			public int BackgroundColor => unchecked((int)0xff000000);
 
+			/// <exception cref="InvalidOperationException">always</exception>
 			public int VsyncNumerator
 			{
 				get { throw new InvalidOperationException(); }
 			}
 
+			/// <exception cref="InvalidOperationException">always</exception>
 			public int VsyncDenominator
 			{
 				get { throw new InvalidOperationException(); }

BizHawk.Client.Common/RomGame.cs

@@ -25,6 +25,7 @@ namespace BizHawk.Client.Common
 		{
 		}
 
+		/// <exception cref="Exception"><paramref name="file"/> does not exist</exception>
 		public RomGame(HawkFile file, string patch)
 		{
 			if (!file.Exists)

BizHawk.Client.Common/XmlGame.cs

@@ -18,6 +18,7 @@ namespace BizHawk.Client.Common
 		public IList<KeyValuePair<string, byte[]>> Assets { get; } = new List<KeyValuePair<string, byte[]>>();
 		public IList<string> AssetFullPaths { get; } = new List<string>(); // TODO: Hack work around, to avoid having to refactor Assets into a object array, should be refactored!
 
+		/// <exception cref="InvalidOperationException">internal error</exception>
 		public static XmlGame Create(HawkFile f)
 		{
 			try

BizHawk.Client.Common/config/ConfigService.cs

@@ -30,6 +30,7 @@ namespace BizHawk.Client.Common
 			};
 		}
 
+		/// <exception cref="InvalidOperationException">internal error</exception>
 		public static T Load<T>(string filepath) where T : new()
 		{
 			T config = default(T);

BizHawk.Client.Common/config/ToolDialogSettings.cs

@@ -64,11 +64,8 @@ namespace BizHawk.Client.Common
 			}
 		}
 
-		/// <summary>
-		/// Gets a value that represents the top left corner coordinate, if <see cref="Wndx"/> and <see cref="Wndy"/> form a valid point
-		/// Throws an InvalidOperationException if <see cref="Wndx"/> or <see cref="Wndy"/> is null
-		/// It is expected to check for this before using this property
-		/// </summary>
+		/// <value>the top-left corner of the <see cref="EmuHawk.IToolFormAutoConfig"/>, equivalent to the combined values of <see cref="Wndx"/> and <see cref="Wndy"/></value>
+		/// <exception cref="InvalidOperationException">either <see cref="Wndx"/> or <see cref="Wndy"/> is null (it is expected to check for this before using this property)</exception>
 		[JsonIgnore]
 		public Point TopLeft
 		{

BizHawk.Client.Common/inputAdapters/OverrideAdaptor.cs

@@ -17,6 +17,7 @@ namespace BizHawk.Client.Common
 		private readonly Dictionary<string, float> _floatOverrides = new Dictionary<string, float>();
 		private readonly List<string> _inverses = new List<string>();
 
+		/// <exception cref="InvalidOperationException"><paramref name="button"/> not overridden</exception>
 		public bool IsPressed(string button)
 		{
 			if (_overrides.ContainsKey(button))

BizHawk.Client.Common/lua/EmuLuaLibrary.NES.cs

@@ -60,6 +60,7 @@ namespace BizHawk.Client.Common
 			}
 		}
 
+		/// <exception cref="InvalidOperationException">loaded core is not NESHawk or QuickNes</exception>
 		[LuaMethodExample("if ( nes.getallowmorethaneightsprites( ) ) then\r\n\tconsole.log( \"Gets the NES setting 'Allow more than 8 sprites per scanline' value\" );\r\nend;")]
 		[LuaMethod("getallowmorethaneightsprites", "Gets the NES setting 'Allow more than 8 sprites per scanline' value")]
 		public bool GetAllowMoreThanEightSprites() => Settings switch
@@ -69,6 +70,7 @@ namespace BizHawk.Client.Common
 			_ => throw new InvalidOperationException()
 		};
 
+		/// <exception cref="InvalidOperationException">loaded core is not NESHawk or QuickNes</exception>
 		[LuaMethodExample("local innesget = nes.getbottomscanline( false );")]
 		[LuaMethod("getbottomscanline", "Gets the current value for the bottom scanline value")]
 		public int GetBottomScanline(bool pal = false) => Settings switch
@@ -78,6 +80,7 @@ namespace BizHawk.Client.Common
 			_ => throw new InvalidOperationException()
 		};
 
+		/// <exception cref="InvalidOperationException">loaded core is not NESHawk or QuickNes</exception>
 		[LuaMethodExample("if ( nes.getclipleftandright( ) ) then\r\n\tconsole.log( \"Gets the current value for the Clip Left and Right sides option\" );\r\nend;")]
 		[LuaMethod("getclipleftandright", "Gets the current value for the Clip Left and Right sides option")]
 		public bool GetClipLeftAndRight() => Settings switch
@@ -87,6 +90,7 @@ namespace BizHawk.Client.Common
 			_ => throw new InvalidOperationException()
 		};
 
+		/// <exception cref="InvalidOperationException">loaded core is not NESHawk or QuickNes</exception>
 		[LuaMethodExample("if ( nes.getdispbackground( ) ) then\r\n\tconsole.log( \"Indicates whether or not the bg layer is being displayed\" );\r\nend;")]
 		[LuaMethod("getdispbackground", "Indicates whether or not the bg layer is being displayed")]
 		public bool GetDisplayBackground() => Settings switch
@@ -96,6 +100,7 @@ namespace BizHawk.Client.Common
 			_ => throw new InvalidOperationException()
 		};
 
+		/// <exception cref="InvalidOperationException">loaded core is not NESHawk or QuickNes</exception>
 		[LuaMethodExample("if ( nes.getdispsprites( ) ) then\r\n\tconsole.log( \"Indicates whether or not sprites are being displayed\" );\r\nend;")]
 		[LuaMethod("getdispsprites", "Indicates whether or not sprites are being displayed")]
 		public bool GetDisplaySprites() => Settings switch
@@ -105,6 +110,7 @@ namespace BizHawk.Client.Common
 			_ => throw new InvalidOperationException()
 		};
 
+		/// <exception cref="InvalidOperationException">loaded core is not NESHawk or QuickNes</exception>
 		[LuaMethodExample("local innesget = nes.gettopscanline(false);")]
 		[LuaMethod("gettopscanline", "Gets the current value for the top scanline value")]
 		public int GetTopScanline(bool pal = false) => Settings switch
@@ -126,6 +132,7 @@ namespace BizHawk.Client.Common
 			}
 		}
 
+		/// <exception cref="InvalidOperationException">loaded core is not NESHawk or QuickNes</exception>
 		[LuaMethodExample("nes.setallowmorethaneightsprites( true );")]
 		[LuaMethod("setallowmorethaneightsprites", "Sets the NES setting 'Allow more than 8 sprites per scanline'")]
 		public void SetAllowMoreThanEightSprites(bool allow)
@@ -145,6 +152,7 @@ namespace BizHawk.Client.Common
 			}
 		}
 
+		/// <exception cref="InvalidOperationException">loaded core is not NESHawk or QuickNes</exception>
 		[LuaMethodExample("nes.setclipleftandright( true );")]
 		[LuaMethod("setclipleftandright", "Sets the Clip Left and Right sides option")]
 		public void SetClipLeftAndRight(bool leftandright)
@@ -164,6 +172,7 @@ namespace BizHawk.Client.Common
 			}
 		}
 
+		/// <exception cref="InvalidOperationException">loaded core is not NESHawk or QuickNes</exception>
 		[LuaMethodExample("nes.setdispbackground( true );")]
 		[LuaMethod("setdispbackground", "Sets whether or not the background layer will be displayed")]
 		public void SetDisplayBackground(bool show)
@@ -181,6 +190,7 @@ namespace BizHawk.Client.Common
 			}
 		}
 
+		/// <exception cref="InvalidOperationException">loaded core is not NESHawk or QuickNes</exception>
 		[LuaMethodExample("nes.setdispsprites( true );")]
 		[LuaMethod("setdispsprites", "Sets whether or not sprites will be displayed")]
 		public void SetDisplaySprites(bool show)
@@ -200,6 +210,7 @@ namespace BizHawk.Client.Common
 			}
 		}
 
+		/// <exception cref="InvalidOperationException">loaded core is not NESHawk or QuickNes</exception>
 		[LuaMethodExample("nes.setscanlines( 10, 20, false );")]
 		[LuaMethod("setscanlines", "sets the top and bottom scanlines to be drawn (same values as in the graphics options dialog). Top must be in the range of 0 to 127, bottom must be between 128 and 239. Not supported in the Quick Nes core")]
 		public void SetScanlines(int top, int bottom, bool pal = false)

BizHawk.Client.Common/lua/LuaLibraryBase.cs

@@ -38,6 +38,7 @@ namespace BizHawk.Client.Common
 			}
 		}
 
+		/// <exception cref="InvalidOperationException">attempted to have Lua running in two host threads at once</exception>
 		public static void SetCurrentThread(LuaFile luaFile)
 		{
 			lock (ThreadMutex)

BizHawk.Client.Common/lua/LuaSandbox.cs

@@ -101,6 +101,7 @@ namespace BizHawk.Client.Common
 			return sandbox;
 		}
 
+		/// <exception cref="InvalidOperationException">could not get sandbox reference for thread (<see cref="CreateSandbox"/> has not been called)</exception>
 		public static LuaSandbox GetSandbox(Lua thread)
 		{
 			// this is just placeholder.

BizHawk.Client.Common/miniz/MinizZipWriter.cs

@@ -14,6 +14,7 @@ namespace BizHawk.Client.Common.Miniz
 		private uint _flags;
 		private static readonly byte[] _shitcock = new byte[32 * 1024 * 1024];
 
+		/// <exception cref="InvalidOperationException">unmanaged call failed</exception>
 		public MinizZipWriter(string path, int compressionlevel)
 		{
 			_zip = Marshal.AllocHGlobal(128);
@@ -54,6 +55,7 @@ namespace BizHawk.Client.Common.Miniz
 			}
 		}
 
+		/// <exception cref="InvalidOperationException">unmanaged call failed</exception>
 		public void WriteItem(string name, Action<Stream> callback)
 		{
 			lock (_shitcock)

BizHawk.Client.Common/movie/MovieSession.cs

@@ -446,6 +446,7 @@ namespace BizHawk.Client.Common
 		public bool? PreviousSNES_InSnes9x { get; set; }
 		public bool? PreviousGBA_UsemGBA { get; set; }
 
+		/// <exception cref="MoviePlatformMismatchException"><paramref name="record"/> is <see langword="false"/> and <paramref name="movie"/>.<see cref="IMovie.SystemID"/> does not match <paramref name="emulator"/>.<see cref="IEmulator.SystemId"/></exception>
 		public void QueueNewMovie(IMovie movie, bool record, IEmulator emulator)
 		{
 			if (!record) // The semantics of record is that we are starting a new movie, and even wiping a pre-existing movie with the same path, but non-record means we are loading an existing movie into playback mode

BizHawk.Client.Common/movie/bk2/StringLogs.cs

@@ -9,7 +9,10 @@ namespace BizHawk.Client.Common
 	public static class StringLogUtil
 	{
 		public static bool DefaultToDisk { get; set; }
+
 		public static bool DefaultToAWE { get; set; }
+
+		/// <exception cref="InvalidOperationException"><see cref="DefaultToAWE"/> is <see langword="true"/> but not running on Windows host</exception>
 		public static IStringLog MakeStringLog()
 		{
 			if (DefaultToDisk)

BizHawk.Client.Common/movie/tasproj/TasMovie.cs

@@ -46,6 +46,7 @@ namespace BizHawk.Client.Common
 			WasLagged = TasLagLog.History(index + 1)
 		};
 
+		/// <exception cref="InvalidOperationException">loaded core does not implement <see cref="IStatable"/></exception>
 		public TasMovie(string path, bool startsFromSavestate = false)
 			: base(path)
 		{
@@ -66,6 +67,7 @@ namespace BizHawk.Client.Common
 			CurrentBranch = -1;
 		}
 
+		/// <exception cref="InvalidOperationException">loaded core does not implement <see cref="IStatable"/></exception>
 		public TasMovie(bool startsFromSavestate = false)
 		{
 			if (!Global.Emulator.HasSavestates())

BizHawk.Client.Common/movie/tasproj/TasStateManager.cs

@@ -33,6 +33,7 @@ namespace BizHawk.Client.Common
 			(int)((ulong)Settings.DiskCapacityMb * 1024 * 1024 / _expectedStateSize);
 		private int FileStateGap => 1 << Settings.FileStateGap;
 
+		/// <exception cref="InvalidOperationException">loaded core expects savestate size of <c>0 B</c></exception>
 		public TasStateManager(TasMovie movie)
 		{
 			_movie = movie;

BizHawk.Client.Common/rewind/StreamBlobDatabase.cs

@@ -186,6 +186,7 @@ namespace BizHawk.Client.Common
 			return _mHead.Value.Index;
 		}
 
+		/// <exception cref="InvalidOperationException">empty</exception>
 		public ListItem Pop()
 		{
 			if (_mHead == null)
@@ -207,6 +208,7 @@ namespace BizHawk.Client.Common
 			return ret;
 		}
 
+		/// <exception cref="InvalidOperationException">empty</exception>
 		public ListItem Peek()
 		{
 			if (_mHead == null)
@@ -217,6 +219,7 @@ namespace BizHawk.Client.Common
 			return _mHead.Value;
 		}
 
+		/// <exception cref="InvalidOperationException">empty</exception>
 		public ListItem Dequeue()
 		{
 			if (_mTail == null)

BizHawk.Client.Common/tools/CheatList.cs

@@ -109,6 +109,7 @@ namespace BizHawk.Client.Common
 			Changes = false;
 		}
 
+		/// <exception cref="ArgumentNullException"><paramref name="cheat"/> is null</exception>
 		public void Add(Cheat cheat)
 		{
 			if (cheat is null)

BizHawk.Client.Common/tools/RamSearchEngine.cs

@@ -223,6 +223,7 @@ namespace BizHawk.Client.Common
 
 		public MemoryDomain Domain => _settings.Domain;
 
+		/// <exception cref="InvalidOperationException">(from setter) <see cref="Mode"/> is <see cref="Settings.SearchMode.Fast"/> and <paramref name="value"/> is not <see cref="Compare.Changes"/></exception>
 		public Compare CompareTo
 		{
 			get => _compareTo;
@@ -268,6 +269,7 @@ namespace BizHawk.Client.Common
 			_settings.BigEndian = bigEndian;
 		}
 
+		/// <exception cref="InvalidOperationException"><see cref="Mode"/> is <see cref="Settings.SearchMode.Fast"/> and <paramref name="type"/> is <see cref="PreviousType.LastFrame"/></exception>
 		public void SetPreviousType(PreviousType type)
 		{
 			if (_settings.Mode == Settings.SearchMode.Fast)

BizHawk.Client.Common/tools/Watch/Watch.cs

@@ -620,9 +620,8 @@ namespace BizHawk.Client.Common
 			}
 		}
 
-		/// <summary>
-		/// Gets the current <see cref="MemoryDomain"/>
-		/// </summary>
+		/// <value>the domain of <see cref="Address"/></value>
+		/// <exception cref="InvalidOperationException">(from setter) <paramref name="value"/> does not have the same name as this property's value</exception>
 		public MemoryDomain Domain
 		{
 			get

BizHawk.Client.Common/tools/Watch/WatchList/WatchList.cs

@@ -114,9 +114,6 @@ namespace BizHawk.Client.Common
 		/// </summary>
 		/// <param name="array">The one-dimension <see cref="Array"/> that will serve as destination to copy</param>
 		/// <param name="arrayIndex">Zero-based index where the copy should starts</param>
-		/// <exception cref="ArgumentNullException"></exception>
-		/// <exception cref="ArgumentOutOfRangeException"></exception>
-		/// <exception cref="ArgumentException"></exception>
 		public void CopyTo(Watch[] array, int arrayIndex)
 		{
 			_watchList.CopyTo(array, arrayIndex);
@@ -158,7 +155,6 @@ namespace BizHawk.Client.Common
 		/// </summary>
 		/// <param name="index">The zero-base index where the <see cref="Watch"/> should be inserted</param>
 		/// <param name="watch"><see cref="Watch"/> to insert</param>
-		/// <exception cref="ArgumentOutOfRangeException"></exception>
 		public void Insert(int index, Watch watch)
 		{
 			_watchList.Insert(index, watch);
@@ -168,7 +164,6 @@ namespace BizHawk.Client.Common
 		/// Removes item at the specified index
 		/// </summary>
 		/// <param name="index">Zero-based index of the <see cref="Watch"/> to remove</param>
-		/// <exception cref="ArgumentOutOfRangeException"></exception>
 		public void RemoveAt(int index)
 		{
 			_watchList.RemoveAt(index);