better documentation of IEMulatorSErvices

BizHawk.Emulation.Common/Interfaces/IEmulator.cs

@@ -2,6 +2,11 @@
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This service defines a core as a core. It is the primary service
+	/// and the absolute minimum requirement to have a functional core in BizHawk
+	/// a client can not operate without this minimum requirement
+	/// </summary>
 	public interface IEmulator : IEmulatorService, IDisposable
 	{
 		/// <summary>

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

@@ -3,7 +3,8 @@
 namespace BizHawk.Emulation.Common
 {
 	/// <summary>
-	/// This service manages the communication from the core to the Code/Data logging tool
+	/// This service manages the communication from the core to the Code/Data logging tool,
+	/// If available then the Code/Data logging tool will be exposed in the client
 	/// </summary>
 	public interface ICodeDataLogger : IEmulatorService
 	{

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

@@ -4,7 +4,7 @@ namespace BizHawk.Emulation.Common
 {
 	/// <summary>
 	/// This service manages debugging capabilities from the core to the client.  Tools such as the debugger make use of this, as well as lua scripting
-	/// This service specifically maanges getting/setting cpu registers, managing breakpoints, and stepping through cpu instructions
+	/// This service specifically manages getting/setting cpu registers, managing breakpoints, and stepping through cpu instructions
 	/// Providing a disassembly is managed by another service, these are aspects outside of the disassembler that are essential to debugging tools
 	/// Tools like the debugger will gracefully degrade based on the availability of each component of this service,
 	/// it is expected that any of these features will throw a NotImplementedException if not implemented, and the client will manage accordingly
@@ -14,16 +14,16 @@ namespace BizHawk.Emulation.Common
 		/// <summary>
 		/// Returns a list of Cpu registers and their current state
 		/// </summary>
-		/// <returns></returns>
 		IDictionary<string, RegisterValue> GetCpuFlagsAndRegisters();
 
 		/// <summary>
 		/// Sets a given Cpu register to the given value
 		/// </summary>
-		/// <param name="register"></param>
-		/// <param name="value"></param>
 		void SetCpuRegister(string register, int value);
 
+		/// <summary>
+		/// A memory callback implementation that manages memory callback functionality
+		/// </summary>
 		IMemoryCallbackSystem MemoryCallbacks { get; }
 
 		/// <summary>

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

@@ -1,7 +1,8 @@
 namespace BizHawk.Emulation.Common
 {
 	/// <summary>
-	/// Specifies an interface for returning the state of a LED drive light such as on Disk and CD Drives
+	/// Specifies an interface for returning the state of a LED drive light such as on Disk and CD Drives,
+	/// If available the client will display a light that turns on and off based on the drive light status
 	/// </summary>
 	public interface IDriveLight : IEmulatorService
 	{

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

@@ -12,7 +12,7 @@ namespace BizHawk.Emulation.Common
 	/// If this service is available the client can provide UI for the user to manage these settings
 	/// </summary>
 	/// <typeparam name="TSettings">The Type of the object that represent regular settings (settings that can be changed during the lifespan of a core instance</typeparam>
-	/// <typeparam name="TSync">The Type of the object that represents sync settings (settings that can not change during hte lifespan of the core and are required for movie sync</typeparam>
+	/// <typeparam name="TSync">The Type of the object that represents sync settings (settings that can not change during the lifespan of the core and are required for movie sync</typeparam>
 	public interface ISettable<TSettings, TSync> : IEmulatorService
 	{
 		// in addition to these methods, it's expected that the constructor or Load() method

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

@@ -1,7 +1,13 @@
 namespace BizHawk.Emulation.Common
 {
-	public enum SyncSoundMode { Sync, Async };
-
+	public enum SyncSoundMode { Sync, Async };
+
+	/// <summary>
+	/// This service provides the ability to output sound from the client,
+	/// If available the client will provide sound ouput
+	/// If unavailable the client will fallback to a default sound implementation
+	/// that generates empty samples (silence)
+	/// </summary>
 	public interface ISoundProvider : IEmulatorService
 	{
 		/// <summary>

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

@@ -6,7 +6,7 @@ namespace BizHawk.Emulation.Common
 	/// This service manages the logic of sending and receiving savestates from the core
 	/// If this service is available, client apps will expose features for making savestates and that utilize savestates (such as rewind))
 	/// If unavailable these options will not be exposed
-	/// Additionally many tools depends on savestates such as TAStudio, these will only be available if this service is implmeented
+	/// Additionally many tools depend on savestates such as TAStudio, these will only be available if this service is implemented
 	/// </summary>
 	public interface IStatable : IEmulatorService
 	{

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

@@ -2,10 +2,15 @@
 {
 	/// <summary>
 	/// This service provides the ability to pass video output to the client
-	/// If available the client will display video output to the user
+	/// If available the client will display video output to the user,
+	/// If unavailable the client will fall back to a default video implementation, presumably
+	/// a black screen of some arbitrary size
 	/// </summary>
 	public interface IVideoProvider : IEmulatorService
 	{
+		/// <summary>
+		/// Returns a framebuffer of the current video content
+		/// </summary>
 		int[] GetVideoBuffer();
 
 		// put together, these describe a metric on the screen
@@ -15,8 +20,22 @@
 		int VirtualWidth { get; }
 		int VirtualHeight { get; }
 
+		/// <summary>
+		/// The width of the frame buffer
+		/// </summary>
 		int BufferWidth { get; }
+
+		/// <summary>
+		/// The height of the frame buffer
+		/// </summary>
 		int BufferHeight { get; }
+
+		/// <summary>
+		/// The default color when no other color is applied
+		/// Often cores will set this to something other than black
+		/// to show that the core is in fact loaded and frames are rendering
+		/// which is less obvious if it is the same as the default video output
+		/// </summary>
 		int BackgroundColor { get; }
 	}
 }