Return success bool from `OpenRom` APIs (squashed PR #3514)

* Return success bool from `OpenRom` APIs

* Finish propagating, update docs for other recently changed methods too

Co-authored-by: YoshiRulz <OSSYoshiRulz@gmail.com>

src/BizHawk.Client.Common/Api/Classes/EmuClientApi.cs

@@ -142,7 +142,8 @@ namespace BizHawk.Client.Common
 
 		public void OnStateSaved(object sender, string stateName) => StateSaved?.Invoke(sender, new StateSavedEventArgs(stateName));
 
-		public void OpenRom(string path) => _mainForm.LoadRom(path, new LoadRomArgs { OpenAdvanced = OpenAdvancedSerializer.ParseWithLegacy(path) });
+		public bool OpenRom(string path)
+			=> _mainForm.LoadRom(path, new LoadRomArgs { OpenAdvanced = OpenAdvancedSerializer.ParseWithLegacy(path) });
 
 		public void Pause() => _mainForm.PauseEmulator();
 

src/BizHawk.Client.Common/Api/Interfaces/IEmuClientApi.cs

@@ -88,6 +88,7 @@ namespace BizHawk.Client.Common
 		/// Load a savestate specified by its name
 		/// </summary>
 		/// <param name="name">Savestate friendly name</param>
+		/// <returns><see langword="true"/> iff succeeded</returns>
 		bool LoadState(string name);
 
 		/// <summary>
@@ -125,7 +126,7 @@ namespace BizHawk.Client.Common
 		/// <param name="stateName">User friendly name for saved state</param>
 		void OnStateSaved(object sender, string stateName);
 
-		void OpenRom(string path);
+		bool OpenRom(string path);
 
 		void Pause();
 

src/BizHawk.Client.Common/Api/Interfaces/ISaveStateApi.cs

@@ -2,8 +2,12 @@
 {
 	public interface ISaveStateApi : IExternalApi
 	{
+		/// <param name="path">absolute path to <c>.State</c> file</param>
+		/// <returns><see langword="true"/> iff succeeded</returns>
 		bool Load(string path, bool suppressOSD = false);
 
+		/// <param name="slotNum"><c>1..10</c></param>
+		/// <returns><see langword="true"/> iff succeeded</returns>
 		bool LoadSlot(int slotNum, bool suppressOSD = false);
 
 		void Save(string path, bool suppressOSD = false);

src/BizHawk.Client.Common/lua/CommonLibs/ClientLuaLibrary.cs

@@ -196,13 +196,14 @@ namespace BizHawk.Client.Common
 		public void OpenRamSearch()
 			=> APIs.Tool.OpenRamSearch();
 
-		[LuaMethodExample("client.openrom( \"C:\\\" );")]
-		[LuaMethod("openrom", "opens the Open ROM dialog")]
-		public void OpenRom(string path)
+		[LuaMethodExample("client.openrom( \"C:\\rom.bin\" );")]
+		[LuaMethod("openrom", "Loads a ROM from the given path. Returns true if the ROM was successfully loaded, otherwise false.")]
+		public bool OpenRom(string path)
 		{
 			_luaLibsImpl.IsRebootingCore = true;
-			APIs.EmuClient.OpenRom(path);
+			var success = APIs.EmuClient.OpenRom(path);
 			_luaLibsImpl.IsRebootingCore = false;
+			return success;
 		}
 
 		[LuaMethodExample("client.opentasstudio( );")]

src/BizHawk.Client.Common/lua/CommonLibs/SaveStateLuaLibrary.cs

@@ -10,7 +10,7 @@ namespace BizHawk.Client.Common
 		public override string Name => "savestate";
 
 		[LuaMethodExample("savestate.load( \"C:\\state.bin\" );")]
-		[LuaMethod("load", "Loads a savestate with the given path. If EmuHawk is deferring quicksaves, to TAStudio for example, that form will do what it likes (and the path is ignored).")]
+		[LuaMethod("load", "Loads a savestate with the given path. Returns true iff succeeded. If EmuHawk is deferring quicksaves, to TAStudio for example, that form will do what it likes (and the path is ignored).")]
 		public bool Load(string path, bool suppressOSD = false)
 		{
 			_luaLibsImpl.IsUpdateSupressed = true;
@@ -20,7 +20,7 @@ namespace BizHawk.Client.Common
 		}
 
 		[LuaMethodExample("savestate.loadslot( 7 );")]
-		[LuaMethod("loadslot", "Loads the savestate at the given slot number (must be an integer between 0 and 9). If EmuHawk is deferring quicksaves, to TAStudio for example, that form will do what it likes with the slot number.")]
+		[LuaMethod("loadslot", "Loads the savestate at the given slot number (must be an integer between 1 and 10). Returns true iff succeeded. If EmuHawk is deferring quicksaves, to TAStudio for example, that form will do what it likes with the slot number.")]
 		public bool LoadSlot(int slotNum, bool suppressOSD = false)
 		{
 			_luaLibsImpl.IsUpdateSupressed = true;
@@ -35,7 +35,7 @@ namespace BizHawk.Client.Common
 			=> APIs.SaveState.Save(path, suppressOSD);
 
 		[LuaMethodExample("savestate.saveslot( 7 );")]
-		[LuaMethod("saveslot", "Saves a state at the given save slot (must be an integer between 0 and 9). If EmuHawk is deferring quicksaves, to TAStudio for example, that form will do what it likes with the slot number.")]
+		[LuaMethod("saveslot", "Saves a state at the given save slot (must be an integer between 1 and 10). If EmuHawk is deferring quicksaves, to TAStudio for example, that form will do what it likes with the slot number.")]
 		public void SaveSlot(int slotNum, bool suppressOSD = false)
 			=> APIs.SaveState.SaveSlot(slotNum, suppressOSD);
 	}

src/BizHawk.Client.EmuHawk/MainForm.Events.cs

@@ -307,7 +307,7 @@ namespace BizHawk.Client.EmuHawk
 				{
 					OpenAdvanced = new OpenAdvanced_LibretroNoGame(Config.LibretroCore)
 				};
-				LoadRom("", argsNoGame);
+				_ = LoadRom(string.Empty, argsNoGame);
 				return;
 			}
 
@@ -341,7 +341,7 @@ namespace BizHawk.Client.EmuHawk
 			if (result is null) return;
 			FileInfo file = new(result);
 			Config.PathEntries.LastRomPath = file.DirectoryName;
-			LoadRom(file.FullName, args);
+			_ = LoadRom(file.FullName, args);
 		}
 
 		private void CloseRomMenuItem_Click(object sender, EventArgs e)

src/BizHawk.Client.EmuHawk/MainForm.FileLoader.cs

@@ -99,13 +99,13 @@ namespace BizHawk.Client.EmuHawk
 				: StartNewMovie(MovieSession.Get(filename), false);
 		}
 
-		private void LoadRom(string filename, string archive = null)
+		private bool LoadRom(string filename, string archive = null)
 		{
 			var args = new LoadRomArgs
 			{
 				OpenAdvanced = new OpenAdvanced_OpenRom {Path = filename}
 			};
-			LoadRom(filename, args);
+			return LoadRom(filename, args);
 		}
 
 		private bool LoadStateFile(string filename, string archive = null)
@@ -262,7 +262,7 @@ namespace BizHawk.Client.EmuHawk
 						switch (value)
 						{
 							case LoadOrdering.Rom:
-								LoadRom(filename, fileInformation.ArchiveName);
+								_ = LoadRom(filename, fileInformation.ArchiveName);
 								break;
 							case LoadOrdering.State:
 								_ = LoadStateFile(filename, fileInformation.ArchiveName);

src/BizHawk.Client.EmuHawk/MainForm.cs

@@ -578,7 +578,7 @@ namespace BizHawk.Client.EmuHawk
 				// Commandline should always override auto-load
 				var ioa = OpenAdvancedSerializer.ParseWithLegacy(_argParser.cmdRom);
 				if (ioa is OpenAdvanced_OpenRom oaor) ioa = new OpenAdvanced_OpenRom { Path = oaor.Path.MakeAbsolute() }; // fixes #3224; should this be done for all the IOpenAdvanced types? --yoshi
-				LoadRom(ioa.SimplePath, new LoadRomArgs { OpenAdvanced = ioa });
+				_ = LoadRom(ioa.SimplePath, new LoadRomArgs { OpenAdvanced = ioa });
 				if (Game.IsNullInstance())
 				{
 					ShowMessageBox(owner: null, $"Failed to load {_argParser.cmdRom} specified on commandline");
@@ -2424,7 +2424,7 @@ namespace BizHawk.Client.EmuHawk
 				initDir: Config.PathEntries.RomAbsolutePath(Emulator.SystemId));
 			if (result is null) return;
 			var filePath = new FileInfo(result).FullName;
-			LoadRom(filePath, new LoadRomArgs { OpenAdvanced = new OpenAdvanced_OpenRom { Path = filePath } });
+			_ = LoadRom(filePath, new LoadRomArgs { OpenAdvanced = new OpenAdvanced_OpenRom { Path = filePath } });
 		}
 
 		private void CoreSyncSettings(object sender, RomLoader.SettingsLoadArgs e)
@@ -3677,7 +3677,7 @@ namespace BizHawk.Client.EmuHawk
 						// Retry loading the ROM here. This leads to recursion, as the original call to LoadRom has not exited yet,
 						// but unless the user tries and fails to set his firmware a lot of times, nothing should happen.
 						// Refer to how RomLoader implemented its LoadRom method for a potential fix on this.
-						LoadRom(e.RomPath, _currentLoadRomArgs);
+						_ = LoadRom(e.RomPath, _currentLoadRomArgs);
 					}
 				}
 			}
@@ -4828,7 +4828,7 @@ namespace BizHawk.Client.EmuHawk
 			//in case this all sounds insanely sketchy to you, remember, the main 99% use case is double clicking roms in explorer
 
 			//BANZAIIIIIIIIIIIIIIIIIIIIIIIIIII
-			LoadRom(args[0]);
+			_ = LoadRom(args[0]);
 		}
 
 		public IQuickBmpFile QuickBmpFile { get; } = EmuHawk.QuickBmpFile.INSTANCE;

src/BizHawk.Client.EmuHawk/RetroAchievements/RAIntegration.cs

@@ -125,7 +125,7 @@ namespace BizHawk.Client.EmuHawk
 				Marshal.Copy(name, 0, buffer, Math.Min(name.Length, 256));
 			};
 			_resetEmulator = () => _mainForm.RebootCore();
-			_loadROM = path => _mainForm.LoadRom(path, new LoadRomArgs { OpenAdvanced = OpenAdvancedSerializer.ParseWithLegacy(path) });
+			_loadROM = path => _ = _mainForm.LoadRom(path, new LoadRomArgs { OpenAdvanced = OpenAdvancedSerializer.ParseWithLegacy(path) });
 
 			RA.InstallSharedFunctionsExt(_isActive, _unpause, _pause, _rebuildMenu, _estimateTitle, _resetEmulator, _loadROM);
 

src/BizHawk.Client.EmuHawk/tools/MultiDiskBundler/MultiDiskBundler.cs

@@ -133,7 +133,7 @@ namespace BizHawk.Client.EmuHawk
 			Close();
 
 			var lra = new LoadRomArgs { OpenAdvanced = new OpenAdvanced_OpenRom { Path = fileInfo.FullName } };
-			MainForm.LoadRom(fileInfo.FullName, lra);
+			_ = MainForm.LoadRom(fileInfo.FullName, lra);
 		}
 
 		private void AddButton_Click(object sender, EventArgs e)