From 7b336664b9bee0ca8c6e1f76a89d15802546a222 Mon Sep 17 00:00:00 2001 From: adelikat Date: Wed, 19 Apr 2017 09:41:26 -0500 Subject: [PATCH] fix ups to the documentation of service interfaces --- .../Interfaces/Services/ICodeDataLogger.cs | 1 + .../Interfaces/Services/IDebuggable.cs | 14 ++++++------ .../Interfaces/Services/IInputPollable.cs | 8 +++---- .../Interfaces/Services/IRegionable.cs | 2 +- .../Interfaces/Services/ISaveRam.cs | 10 ++++----- .../Interfaces/Services/ISettable.cs | 4 ++-- .../Interfaces/Services/IVideoProvider.cs | 22 +++++++++++++++---- 7 files changed, 38 insertions(+), 23 deletions(-) diff --git a/BizHawk.Emulation.Common/Interfaces/Services/ICodeDataLogger.cs b/BizHawk.Emulation.Common/Interfaces/Services/ICodeDataLogger.cs index 48086f58a6..3e89564d9c 100644 --- a/BizHawk.Emulation.Common/Interfaces/Services/ICodeDataLogger.cs +++ b/BizHawk.Emulation.Common/Interfaces/Services/ICodeDataLogger.cs @@ -54,6 +54,7 @@ namespace BizHawk.Emulation.Common bool Has(string blockname); /// + /// Gets or sets a value indicating whether the status is active. /// This is just a hook, if needed, to readily suspend logging, without having to rewire the core /// bool Active { get; set; } diff --git a/BizHawk.Emulation.Common/Interfaces/Services/IDebuggable.cs b/BizHawk.Emulation.Common/Interfaces/Services/IDebuggable.cs index b2d2357ca7..54f3aba6df 100644 --- a/BizHawk.Emulation.Common/Interfaces/Services/IDebuggable.cs +++ b/BizHawk.Emulation.Common/Interfaces/Services/IDebuggable.cs @@ -3,8 +3,8 @@ namespace BizHawk.Emulation.Common { /// - /// 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 manages getting/setting cpu registers, managing breakpoints, and stepping through cpu instructions + /// 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 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 @@ -12,17 +12,17 @@ namespace BizHawk.Emulation.Common public interface IDebuggable : IEmulatorService { /// - /// Returns a list of Cpu registers and their current state + /// Returns a list of CPU registers and their current state /// IDictionary GetCpuFlagsAndRegisters(); /// - /// Sets a given Cpu register to the given value + /// Sets a given CPU register to the given value /// void SetCpuRegister(string register, int value); /// - /// A memory callback implementation that manages memory callback functionality + /// Gets a memory callback implementation that manages memory callback functionality /// IMemoryCallbackSystem MemoryCallbacks { get; } @@ -38,8 +38,8 @@ namespace BizHawk.Emulation.Common void Step(StepType type); /// - /// Total number of cpu cycles since the beginning of the core's lifecycle - /// Note that the cpu in this case is the "main" cpu, for some cores that may be somewhat subjective + /// Gets the total number of CPU cycles since the beginning of the core's lifecycle + /// Note that the CPU in this case is the "main" CPU, for some cores that may be somewhat subjective /// int TotalExecutedCycles { get; } // TODO: this should probably be a long, but most cores were using int, oh well } diff --git a/BizHawk.Emulation.Common/Interfaces/Services/IInputPollable.cs b/BizHawk.Emulation.Common/Interfaces/Services/IInputPollable.cs index 9993d37164..468bf81fb6 100644 --- a/BizHawk.Emulation.Common/Interfaces/Services/IInputPollable.cs +++ b/BizHawk.Emulation.Common/Interfaces/Services/IInputPollable.cs @@ -1,23 +1,23 @@ namespace BizHawk.Emulation.Common { /// - /// This service specifices the interaction of the client and the core in terms of the state of input polling + /// This service specifies 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 + /// 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 /// public interface IInputPollable : IEmulatorService { /// - /// The lag count. + /// Gets or sets the current lag count. /// int LagCount { get; set; } /// - /// If the current frame is a lag frame. + /// Gets or sets a value indicating whether or not current frame is a lag frame. /// All cores should define it the same, a lag frame is a frame in which input was not polled. /// bool IsLagFrame { get; set; } diff --git a/BizHawk.Emulation.Common/Interfaces/Services/IRegionable.cs b/BizHawk.Emulation.Common/Interfaces/Services/IRegionable.cs index 5a6dd777c2..26178d3da6 100644 --- a/BizHawk.Emulation.Common/Interfaces/Services/IRegionable.cs +++ b/BizHawk.Emulation.Common/Interfaces/Services/IRegionable.cs @@ -1,7 +1,7 @@ namespace BizHawk.Emulation.Common { /// - /// This service provides the means for a core to specify region information to the client, such NTSC vs PAL + /// This service provides the means for a core to specify region information to the client, such NTSC versus PAL /// If provided the client will use this to asses FPS and also use it to calculate movie times /// public interface IRegionable : IEmulatorService diff --git a/BizHawk.Emulation.Common/Interfaces/Services/ISaveRam.cs b/BizHawk.Emulation.Common/Interfaces/Services/ISaveRam.cs index b78d9d6801..e7df3742ab 100644 --- a/BizHawk.Emulation.Common/Interfaces/Services/ISaveRam.cs +++ b/BizHawk.Emulation.Common/Interfaces/Services/ISaveRam.cs @@ -1,25 +1,25 @@ namespace BizHawk.Emulation.Common { /// - /// This service provdes the system by which a client can request SRam data to be stored by the client + /// This service provides 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, 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 + /// In addition the client will provide features like SRAM-anchored movies, and ways to clear SaveRam /// public interface ISaveRam : IEmulatorService { /// - /// return a copy of the saveram. editing it won't do you any good unless you later call StoreSaveRam() + /// Returns a copy of the SaveRAM. Editing it won't do you any good unless you later call StoreSaveRam() /// byte[] CloneSaveRam(); /// - /// store new saveram to the emu core. the data should be the same size as the return from ReadSaveRam() + /// store new SaveRAM to the emu core. the data should be the same size as the return from ReadSaveRam() /// void StoreSaveRam(byte[] data); /// - /// Whether or not Save ram has been modified since the last save + /// Gets a value indicating whether or not SaveRAM has been modified since the last save /// bool SaveRamModified { get; } } diff --git a/BizHawk.Emulation.Common/Interfaces/Services/ISettable.cs b/BizHawk.Emulation.Common/Interfaces/Services/ISettable.cs index 0bec101359..6c5ded18ce 100644 --- a/BizHawk.Emulation.Common/Interfaces/Services/ISettable.cs +++ b/BizHawk.Emulation.Common/Interfaces/Services/ISettable.cs @@ -24,7 +24,7 @@ namespace BizHawk.Emulation.Common /// VERY IMPORTANT: changes to the object returned by this function SHOULD NOT have any effect on emulation /// (unless the object is later passed to PutSettings) /// - /// a json-serializable object + /// a JSON serializable object TSettings GetSettings(); /// @@ -33,7 +33,7 @@ namespace BizHawk.Emulation.Common /// VERY IMPORTANT: changes to the object returned by this function MUST NOT have any effect on emulation /// (unless the object is later passed to PutSyncSettings) /// - /// a json-serializable object + /// a JSON serializable object TSync GetSyncSettings(); /// diff --git a/BizHawk.Emulation.Common/Interfaces/Services/IVideoProvider.cs b/BizHawk.Emulation.Common/Interfaces/Services/IVideoProvider.cs index 1e7162915d..c619c3f600 100644 --- a/BizHawk.Emulation.Common/Interfaces/Services/IVideoProvider.cs +++ b/BizHawk.Emulation.Common/Interfaces/Services/IVideoProvider.cs @@ -9,7 +9,7 @@ public interface IVideoProvider : IEmulatorService { /// - /// Returns a framebuffer of the current video content + /// Returns a frame buffer of the current video content /// int[] GetVideoBuffer(); @@ -17,21 +17,35 @@ // they should define the smallest size that the buffer can be placed inside such that: // 1. no actual pixel data is lost // 2. aspect ratio is accurate + + /// + /// Gets a value that together with , describes a metric on the screen + /// they should define the smallest size that the buffer can be placed inside such that: + /// 1. no actual pixel data is lost + /// 2. aspect ratio is accurate + /// int VirtualWidth { get; } + + /// + /// Gets a value that together with , describes a metric on the screen + /// they should define the smallest size that the buffer can be placed inside such that: + /// 1. no actual pixel data is lost + /// 2. aspect ratio is accurate + /// int VirtualHeight { get; } /// - /// The width of the frame buffer + /// Gets the width of the frame buffer /// int BufferWidth { get; } /// - /// The height of the frame buffer + /// Gets the height of the frame buffer /// int BufferHeight { get; } /// - /// The default color when no other color is applied + /// Gets 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