More documentaiton for IEmulatorServices, related classes/interfaces, and base implementations

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

@@ -4,6 +4,14 @@ using System.Linq;
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// A generic implementation of IEmulatorService provider that provides
+	/// this functionality to any core.
+	/// The provider will scan an IEmulator and register all IEmulatorServices
+	/// that the core object itself implements.  In addition it provides
+	/// a Register() method to allow the core to pass in any additional services
+	/// </summary>
+	/// <seealso cref="IEmulatorServiceProvider"/> 
 	public class BasicServiceProvider : IEmulatorServiceProvider
 	{
 		private Dictionary<Type, object> Services = new Dictionary<Type, object>();

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

@@ -1,11 +1,21 @@
 using System;
 using System.Collections.Generic;
-using System.Linq;
 
 using BizHawk.Emulation.Common.IEmulatorExtensions;
 
 namespace BizHawk.Emulation.Common
-{
+{
+	/// <summary>
+	/// An implementation of ITraceable that is implementation using only methods
+	/// from IDebuggable, IMemoryDomains, and IDisassemblable
+	/// Useful for ported cores that have these hooks but no trace logging hook,
+	/// This allows for a traceable implementation without the need for additional API
+	/// Note that this technique will always be significantly slower than a direct implementation
+	/// </summary>
+	/// <seealso cref="ITraceable"/> 
+	/// <seealso cref="IDebuggable"/> 
+	/// <seealso cref="IMemoryDomains"/> 
+	/// /// <seealso cref="IDisassemblable"/> 
 	public abstract class CallbackBasedTraceBuffer : ITraceable
 	{
 		public CallbackBasedTraceBuffer(IDebuggable debuggableCore, IMemoryDomains memoryDomains, IDisassemblable disassembler)

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

@@ -4,6 +4,11 @@ using System.Linq;
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This is a generic implementation of IInputCallbackSystem that can be used
+	/// by any core
+	/// </summary>
+	/// <seealso cref="IInputCallbackSystem" />
 	public class InputCallbackSystem : List<Action>, IInputCallbackSystem
 	{
 		public void Call()

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

@@ -4,6 +4,11 @@ using System.Collections.Generic;
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This is a generic implementation of IMemoryCallbackSystem
+	/// that can be used by used by any core
+	/// </summary>
+	/// <seealso cref="IMemoryCallbackSystem" />
 	public class MemoryCallbackSystem : IMemoryCallbackSystem
 	{
 		public MemoryCallbackSystem()

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

@@ -1,10 +1,12 @@
 using System;
-using System.Linq;
-using System.Collections.Generic;
-using System.Collections.ObjectModel;
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// A memory region and the functionality to read/write from it
+	/// as required by the IMemoryDomains service.
+	/// </summary>
+	/// <seealso cref="IMemoryDomains" />
 	public abstract class MemoryDomain
 	{
 		public enum Endian { Big, Little, Unknown }
@@ -26,11 +28,7 @@ namespace BizHawk.Emulation.Common
 		/// <summary>
 		/// creates a memorydomain that references a managed byte array
 		/// </summary>
-		/// <param name="name"></param>
-		/// <param name="endian"></param>
-		/// <param name="data"></param>
 		/// <param name="writable">if false, writes will be ignored</param>
-		/// <returns></returns>
 		[Obsolete]
 		public static MemoryDomain FromByteArray(string name, Endian endian, byte[] data, bool writable = true, int wordSize = 1)
 		{
@@ -42,7 +40,6 @@ namespace BizHawk.Emulation.Common
 		/// </summary>
 		/// <param name="data">must remain valid as long as the MemoryDomain exists!</param>
 		/// <param name="writable">if false, writes will be ignored</param>
-		/// <returns></returns>
 		[Obsolete]
 		public unsafe static MemoryDomain FromIntPtr(string name, long size, Endian endian, IntPtr data, bool writable = true, int wordSize = 1)
 		{
@@ -54,7 +51,6 @@ namespace BizHawk.Emulation.Common
 		/// </summary>
 		/// <param name="data">must remain valid as long as the MemoryDomain exists!</param>
 		/// <param name="writable">if false, writes will be ignored</param>
-		/// <returns></returns>
 		[Obsolete]
 		public unsafe static MemoryDomain FromIntPtrSwap16(string name, long size, Endian endian, IntPtr data, bool writable = true)
 		{

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

@@ -1,7 +1,4 @@
 using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 
 namespace BizHawk.Emulation.Common
 {

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

@@ -1,11 +1,14 @@
 using System;
 using System.Collections.Generic;
-using System.Linq;
-using System.Text;
 using System.Collections.ObjectModel;
+using System.Linq;
 
 namespace BizHawk.Emulation.Common
-{
+{
+	/// <summary>
+	/// A generic implementation of IMemoryDomain that can be used by any core
+	/// </summary>
+	/// <seealso cref="IMemoryDomains" />
 	public class MemoryDomainList : ReadOnlyCollection<MemoryDomain>, IMemoryDomains
 	{
 		private MemoryDomain _mainMemory;

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

@@ -1,5 +1,10 @@
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// A empty implementation of IController that represents the lack of
+	/// a controller interface
+	/// </summary>
+	/// <seealso cref="IController" />
 	public class NullController : IController
 	{
 		public ControllerDefinition Definition { get { return null; } }

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

@@ -2,6 +2,11 @@
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// A default and empty implementation of ISoundProvider
+	/// that simply outputs "silence"
+	/// </summary>
+	/// <seealso cref="ISoundProvider" />
 	public class NullSound : ISoundProvider
 	{
 		private readonly long _spfNumerator;

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

@@ -1,6 +1,10 @@
 namespace BizHawk.Emulation.Common
 {
-	// A default IVideoProvider implementation that simply returns a black screen
+	/// <summary>
+	/// A default IVideoProvider that simply returns
+	/// a black screen at an arbitruary size
+	/// </summary>
+	/// <seealso cref="IVideoProvider" />
 	public class NullVideo : IVideoProvider
 	{
 		public int[] GetVideoBuffer()

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

@@ -1,10 +1,11 @@
-using System.Collections.Generic;
-using System.Linq;
-
-//garbage
+//garbage
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// A generic implementation of ITraceable that can be used by any core
+	/// </summary>
+	/// <seealso cref="ITraceable" />
 	public class TraceBuffer : ITraceable
 	{
 		public TraceBuffer()

BizHawk.Emulation.Common/CoreComms.cs

@@ -4,9 +4,11 @@ namespace BizHawk.Emulation.Common
 {
 	/// <summary>
 	/// This object fascilitates communications between client and core
+	/// and is used by the IEmulator interface
 	/// The primary use is to provide a client => core communication, such as providing client-side callbacks for a core to use
 	/// Any communications that can be described as purely a Core -> Client system, should be provided as an IEmulatorService instead
 	/// </summary>
+	/// <seealso cref="IEmulator" />
 	public class CoreComm
 	{
 		public CoreComm(Action<string> showMessage, Action<string> NotifyMessage)

BizHawk.Emulation.Common/Interfaces/IAsyncSoundProvider.cs

@@ -1,7 +1,11 @@
 using System;
 
 namespace BizHawk.Emulation.Common
-{
+{
+	/// <summary>
+	/// This interface is for legacy sound implementations in some older cores
+	/// This needs to go away, but is provided here, for now
+	/// </summary>
 	public interface IAsyncSoundProvider
 	{
 		void GetSamples(short[] samples);

BizHawk.Emulation.Common/Interfaces/ICoreFileProvider.cs

@@ -2,6 +2,9 @@
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// Defines the means by which firmware, bios and other necessary files are provided to a core that needs them
+	/// </summary>
 	public interface ICoreFileProvider
 	{
 		/// <summary>

BizHawk.Emulation.Common/Interfaces/IEmulatorServiceProvider.cs

@@ -3,6 +3,16 @@ using System.Collections.Generic;
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This interface defines the mechanism by which clients can retrive IEmulatorServices
+	/// from an IEmulator implementation
+	/// An implementation should collect all available IEmulatorService instances.
+	/// This interface defines only the client interaction.  This interface does not specify the means
+	/// by which a service provider will be populated with available services.  However, an implementation
+	/// by design must provide this mechanism
+	/// </summary>
+	/// <seealso cref="IEmulator" /> 
+	/// <seealso cref="IEmulatorService"/> 
 	public interface IEmulatorServiceProvider
 	{
 		/// <summary>
@@ -28,7 +38,7 @@ namespace BizHawk.Emulation.Common
 		object GetService(Type t);
 
 		/// <summary>
-		/// A list of all cuurently registered services available to be called
+		/// A list of all currently registered services available to be retrieved
 		/// </summary>
 		IEnumerable<Type> AvailableServices { get; }
 	}

BizHawk.Emulation.Common/Interfaces/IInputCallbackSystem.cs

@@ -3,7 +3,12 @@ using System.Collections.Generic;
 
 namespace BizHawk.Emulation.Common
 {
-	// TODO: This isn't a CoreService, it is a sub class of a core service, it would be nice to make that clear
+	/// <summary>
+	/// This is a property of IInputPollable, and defines the means by which a client
+	/// gets and sets input callbacks in the core.  An input callback should fire any time input is
+	/// polled by the core
+	/// </summary>
+	/// <seealso cref="IInputPollable"/> 
 	public interface IInputCallbackSystem : ICollection<Action>
 	{
 		/// <summary>

BizHawk.Emulation.Common/Interfaces/IMemoryCallbackSystem.cs

@@ -3,6 +3,12 @@ using System.Collections.Generic;
 
 namespace BizHawk.Emulation.Common
 {
+	/// <summary>
+	/// This is a property of IDebuggable, and defines the means by which a client
+	/// gets and sets memory callbacks in the core.  A memory callback should fire any time memory is
+	/// read/written/executed by the core, and depends on the type specified by the callback
+	/// </summary>
+	/// <seealso cref="IDebuggable"/> 
 	public interface IMemoryCallbackSystem : IEnumerable<IMemoryCallback>
 	{
 		/*
@@ -69,6 +75,10 @@ namespace BizHawk.Emulation.Common
 		void Clear();
 	}
 
+	/// <summary>
+	/// This service defines a memory callback used by an IMemoryCallbackSystem implementation
+	/// </summary>
+	/// <seealso cref="IMemoryCallbackSystem"/> 
 	public interface IMemoryCallback
 	{
 		MemoryCallbackType Type { get; }

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

@@ -4,7 +4,8 @@
 	/// 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
+	/// 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>

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

@@ -2,7 +2,7 @@
 {
 	/// <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
+	/// If available, the client will display the link cable status
 	/// </summary>
 	public interface ILinkable : ISpecializedEmulatorService
 	{

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

@@ -3,13 +3,15 @@
 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.
+	/// This service manages the ability for a client to read/write to memory regions of the core,
+	/// It is a list of all avaialble memory domains
+	/// A memory domain is a byte array that respresents the memory of a distinct part of the emulated 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
+	/// All domains should implement both peek and poke.  However, 
+	/// if a domain does not implement poke, 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
+	/// In addition, this is an essential service for effective lua scripting, and many other tools
 	/// </summary>
 	public interface IMemoryDomains : IEnumerable<MemoryDomain>, IEmulatorService
 	{

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

@@ -3,9 +3,8 @@
 	/// <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
-	/// 
+	/// If available, save files will be automatically loaded when loading a ROM,
+	/// In addition the client will provide features like sram-anchored movies, and ways to clear SaveRam
 	/// </summary>
 	public interface ISaveRam : IEmulatorService
 	{

BizHawk.Emulation.Common/ServiceInjector.cs

@@ -1,8 +1,6 @@
 using System;
-using System.Collections.Generic;
 using System.Linq;
-using System.Text;
-using System.Reflection;
+
 using BizHawk.Common.ReflectionExtensions;
 
 namespace BizHawk.Emulation.Common