Add documentation to the Emulation.Common IEmulatorService interfaces

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

@@ -2,6 +2,9 @@
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This service manages the communication from the core to the Code/Data logging tool
+	/// </summary>
 	public interface ICodeDataLogger : IEmulatorService
 	{
 		/// <summary>

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

@@ -2,6 +2,13 @@
 
 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
+	/// 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
+	/// </summary>
 	public interface IDebuggable : IEmulatorService
 	{
 		/// <summary>

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

@@ -4,6 +4,11 @@ using System.Collections.Generic;
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This service provides the means to generate disassembly by the core for a given cpu and memory domain
+	/// Tools such the debugger use this, but also lua scripting, and tools like trace logging and code data logging can make use of this tool
+	/// If unavailable the debugger tool will still be avilable but disable the disassembly window but still be available if the IDebuggable service is available
+	/// </summary>
 	public interface IDisassemblable : IEmulatorService
 	{
 		/// <summary>

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

@@ -1,7 +1,7 @@
 namespace BizHawk.Emulation.Common
 {
 	/// <summary>
-	/// Specifies an interface to 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
 	/// </summary>
 	public interface IDriveLight : IEmulatorService
 	{

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

@@ -1,5 +1,13 @@
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This service specifices the interaction of the client and the core in terms of the state of input polling
+	/// A lag frame is a frame in which input was not polled
+	/// Input callbacks fire whenever input is polled
+	/// This service is used for the lag counter on the front end, if available.  In addition lua script makes use of input callbacks as well as reporting lag status
+	/// Setters for both the count and lag flag are used by tools who offer custom notions of lag
+	/// Additionally, movie support could in theory make use of input callbacks
+	/// </summary>
 	public interface IInputPollable : IEmulatorService
 	{
 		/// <summary>

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

@@ -1,5 +1,9 @@
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This service is use by link cable capable cores to manage the status of the link cable
+	/// If available the client will display the link cable status
+	/// </summary>
 	public interface ILinkable : ISpecializedEmulatorService
 	{
 		/// <summary>

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

@@ -5,9 +5,11 @@ namespace BizHawk.Emulation.Common
 	/// <summary>
 	/// The list of all avaialble memory domains
 	/// A memory domain is a byte array that respresents a distinct part of the emulated system.
-	/// All cores sould implement a CheatDomain that represents the standard cpu bus range used for cheats for that system,
+	/// All cores sould implement a SystemBus that represents the standard cpu bus range used for cheats for that system,
 	/// In order to have a cheat system available for the core
 	/// All domains should implement both peek and poke.  However, if something isn't developed it should throw NotImplementedException rather than silently fail
+	/// If this service is available the client will expose many RAM related tools such as the Hex Editor, Ram Search/Watch, and Cheats
+	/// In addition, this is an essential service for effective lua scripting
 	/// </summary>
 	public interface IMemoryDomains : IEnumerable<MemoryDomain>, IEmulatorService
 	{

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

@@ -1,5 +1,9 @@
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This service provides the means for a core to specify region information to the client, such NTSC vs PAL
+	/// If provided the client will use this to asses FPS and also use it to calculate movie times
+	/// </summary>
 	public interface IRegionable : IEmulatorService
 	{
 		DisplayType Region { get; }

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

@@ -1,5 +1,12 @@
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This service provdes the system by which a client can request SRam data to be stored by the client
+	/// SaveRam encompasses things like battery backed ram, memory cards, and data saved to disk drives
+	/// If available the client will provide features like sram-anchored movies, and ways to clear SaveRam
+	/// In addition save files and such will be automatically loaded when loading a ROM
+	/// 
+	/// </summary>
 	public interface ISaveRam : IEmulatorService
 	{
 		/// <summary>

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

@@ -4,6 +4,15 @@ using System.Reflection;
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This service provides mechanism for the client to set sync and non-sync related settings to the core
+	/// Settings are settings that can changge during the lifetime of the core and do not affect potential movie sync
+	/// Sync Settings do not change during the lifetime of the core and affect movie sync
+	/// If available, Sync settings are stored in movie files and automatically applied when the movie is loaded
+	/// 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>
 	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/IStatable.cs

@@ -3,7 +3,10 @@
 namespace BizHawk.Emulation.Common
 {
 	/// <summary>
-	/// Savestate handling methods
+	/// 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
 	/// </summary>
 	public interface IStatable : IEmulatorService
 	{

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

@@ -3,12 +3,11 @@
 namespace BizHawk.Emulation.Common
 {
 	/// <summary>
-	/// Allows the cpu to dump trace info to a trace stream
+	/// This service allows the core to dump a cpu trace to the client
+	/// If available the Trace Logger tool will be available on the client
 	/// </summary>
 	public interface ITraceable : IEmulatorService
 	{
-		// TODO: would it be faster (considering both disk and screen output) to keep the data as a List<string> directly?
-
 		bool Enabled { get; set; }
 
 		/// <summary>

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

@@ -1,5 +1,9 @@
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This service provides the ability to pass video output to the client
+	/// If available the client will display video output to the user
+	/// </summary>
 	public interface IVideoProvider : IEmulatorService
 	{
 		int[] GetVideoBuffer();