From 19705b78fd88d171b77f79288218224ea210a6af Mon Sep 17 00:00:00 2001 From: YoshiRulz Date: Sat, 28 Dec 2019 05:41:54 +1000 Subject: [PATCH] Improve exception docs in BizHawk.Common --- BizHawk.Common/AWEMemoryStream.cs | 1 + BizHawk.Common/BizInvoke/BizInvoker.cs | 2 + .../BizInvoke/CallingConventionAdapter.cs | 1 + BizHawk.Common/BizInvoke/MemoryBlock.cs | 10 +++-- BizHawk.Common/BizInvoke/MemoryBlockBase.cs | 3 ++ BizHawk.Common/BizInvoke/MemoryBlockUnix.cs | 7 ++++ BizHawk.Common/DeepEquality.cs | 5 +-- BizHawk.Common/Extensions/BufferExtensions.cs | 2 + .../Extensions/CollectionExtensions.cs | 3 +- .../Extensions/ReflectionExtensions.cs | 5 ++- BizHawk.Common/HawkFile.cs | 37 +++++++------------ BizHawk.Common/IImportResolver.cs | 4 +- BizHawk.Common/MutableIntRange.cs | 4 +- BizHawk.Common/OSTailoredCode.cs | 8 +++- BizHawk.Common/QuickCollections.cs | 8 ++++ BizHawk.Common/Serializer.cs | 2 + BizHawk.Common/SwitcherStream.cs | 2 + BizHawk.Common/TempFileManager.cs | 1 + BizHawk.Common/Util.cs | 4 +- 19 files changed, 72 insertions(+), 37 deletions(-) diff --git a/BizHawk.Common/AWEMemoryStream.cs b/BizHawk.Common/AWEMemoryStream.cs index 6efb942a78..c93d64e56a 100644 --- a/BizHawk.Common/AWEMemoryStream.cs +++ b/BizHawk.Common/AWEMemoryStream.cs @@ -383,6 +383,7 @@ namespace BizHawk.Common } } + /// is equivalent to more than uint.MaxValue pages public bool Allocate(int byteSize) { if (!TryAcquirePrivilege()) diff --git a/BizHawk.Common/BizInvoke/BizInvoker.cs b/BizHawk.Common/BizInvoke/BizInvoker.cs index 1acd86f7f2..2e31cd7b4f 100644 --- a/BizHawk.Common/BizInvoke/BizInvoker.cs +++ b/BizHawk.Common/BizInvoke/BizInvoker.cs @@ -60,6 +60,7 @@ namespace BizHawk.Common.BizInvoke /// get an implementation proxy for an interop class /// /// The class type that represents the DLL + /// previously called with public static T GetInvoker(IImportResolver dll, ICallingConventionAdapter adapter) where T : class { @@ -82,6 +83,7 @@ namespace BizHawk.Common.BizInvoke return (T)impl.Create(dll, null, adapter); } + /// this method was previously called with public static T GetInvoker(IImportResolver dll, IMonitor monitor, ICallingConventionAdapter adapter) where T : class { diff --git a/BizHawk.Common/BizInvoke/CallingConventionAdapter.cs b/BizHawk.Common/BizInvoke/CallingConventionAdapter.cs index df6ad89894..24521a2bf2 100644 --- a/BizHawk.Common/BizInvoke/CallingConventionAdapter.cs +++ b/BizHawk.Common/BizInvoke/CallingConventionAdapter.cs @@ -38,6 +38,7 @@ namespace BizHawk.Common.BizInvoke ParameterTypes = parameterTypes.ToList().AsReadOnly(); } + /// does not inherit public ParameterInfo(Type delegateType) { if (!typeof(Delegate).IsAssignableFrom(delegateType)) diff --git a/BizHawk.Common/BizInvoke/MemoryBlock.cs b/BizHawk.Common/BizInvoke/MemoryBlock.cs index 94c509a8f9..7194110027 100644 --- a/BizHawk.Common/BizInvoke/MemoryBlock.cs +++ b/BizHawk.Common/BizInvoke/MemoryBlock.cs @@ -11,9 +11,8 @@ namespace BizHawk.Common.BizInvoke /// private IntPtr _handle; - /// - /// allocate size bytes starting at a particular address - /// + /// allocate bytes starting at a particular address + /// failed to create file mapping public MemoryBlock(ulong start, ulong size) : base(start, size) { _handle = Kernel32.CreateFileMapping( @@ -27,6 +26,7 @@ namespace BizHawk.Common.BizInvoke if (_handle == IntPtr.Zero) throw new InvalidOperationException($"{nameof(Kernel32.CreateFileMapping)}() returned NULL"); } + /// is or failed to map file view public override void Activate() { if (Active) @@ -40,6 +40,7 @@ namespace BizHawk.Common.BizInvoke Active = true; } + /// is or failed to unmap file view public override void Deactivate() { if (!Active) @@ -49,6 +50,7 @@ namespace BizHawk.Common.BizInvoke Active = false; } + /// snapshot already taken, is , or failed to make memory read-only public override void SaveXorSnapshot() { if (_snapshot != null) @@ -71,6 +73,7 @@ namespace BizHawk.Common.BizInvoke ProtectAll(); } + /// is or failed to make memory read-only public override byte[] FullHash() { if (!Active) @@ -116,6 +119,7 @@ namespace BizHawk.Common.BizInvoke } } + /// failed to protect memory public override void Protect(ulong start, ulong length, Protection prot) { if (length == 0) diff --git a/BizHawk.Common/BizInvoke/MemoryBlockBase.cs b/BizHawk.Common/BizInvoke/MemoryBlockBase.cs index 242a600aa0..7768951a2f 100644 --- a/BizHawk.Common/BizInvoke/MemoryBlockBase.cs +++ b/BizHawk.Common/BizInvoke/MemoryBlockBase.cs @@ -47,6 +47,7 @@ namespace BizHawk.Common.BizInvoke protected ulong GetStartAddr(int page) => ((ulong) page << WaterboxUtils.PageShift) + Start; /// Get a stream that can be used to read or write from part of the block. Does not check for or change ! + /// or end (= + ) are outside bounds of memory block ( and ) public Stream GetStream(ulong start, ulong length, bool writer) { if (start < Start) throw new ArgumentOutOfRangeException(nameof(start)); @@ -55,6 +56,8 @@ namespace BizHawk.Common.BizInvoke } /// get a stream that can be used to read or write from part of the block. both reads and writes will be XORed against an earlier recorded snapshot + /// or end (= + ) are outside bounds of memory block ( and ) + /// no snapshot taken (haven't called ) public Stream GetXorStream(ulong start, ulong length, bool writer) { if (start < Start) throw new ArgumentOutOfRangeException(nameof(start)); diff --git a/BizHawk.Common/BizInvoke/MemoryBlockUnix.cs b/BizHawk.Common/BizInvoke/MemoryBlockUnix.cs index ef14d08559..898209a766 100644 --- a/BizHawk.Common/BizInvoke/MemoryBlockUnix.cs +++ b/BizHawk.Common/BizInvoke/MemoryBlockUnix.cs @@ -11,6 +11,8 @@ namespace BizHawk.Common.BizInvoke private int _fd; /// allocate bytes starting at a particular address + /// failed to get file descriptor (never thrown as is thrown first) + /// always public MemoryBlockUnix(ulong start, ulong size) : base(start, size) { throw new NotImplementedException($"{nameof(MemoryBlockUnix)} ctor"); @@ -18,6 +20,7 @@ namespace BizHawk.Common.BizInvoke if (_fd == -1) throw new InvalidOperationException($"{nameof(memfd_create)}() returned -1"); } + /// is or failed to map memory public override void Activate() { if (Active) throw new InvalidOperationException("Already active"); @@ -29,6 +32,7 @@ namespace BizHawk.Common.BizInvoke Active = true; } + /// is or failed to unmap memory public override void Deactivate() { if (!Active) throw new InvalidOperationException("Not active"); @@ -39,6 +43,7 @@ namespace BizHawk.Common.BizInvoke Active = false; } + /// is or failed to make memory read-only public override byte[] FullHash() { if (!Active) throw new InvalidOperationException("Not active"); @@ -52,6 +57,7 @@ namespace BizHawk.Common.BizInvoke return ret; } + /// failed to protect memory public override void Protect(ulong start, ulong length, Protection prot) { if (length == 0) return; @@ -92,6 +98,7 @@ namespace BizHawk.Common.BizInvoke } } + /// snapshot already taken, is , or failed to make memory read-only public override void SaveXorSnapshot() { if (_snapshot != null) throw new InvalidOperationException("Snapshot already taken"); diff --git a/BizHawk.Common/DeepEquality.cs b/BizHawk.Common/DeepEquality.cs index b45e464551..16cec2672c 100644 --- a/BizHawk.Common/DeepEquality.cs +++ b/BizHawk.Common/DeepEquality.cs @@ -51,9 +51,8 @@ namespace BizHawk.Common static MethodInfo ArrayEqualsGeneric = typeof(DeepEquality).GetMethod("ArrayEquals", BindingFlags.NonPublic | BindingFlags.Static); - /// - /// test if two objects are equal field by field (with deep inspection of each field) - /// + /// test if two objects and are equal, field-by-field (with deep inspection of each field) + /// is an array with rank > 1 or is a non-zero-indexed array public static bool DeepEquals(object o1, object o2) { if (o1 == o2) diff --git a/BizHawk.Common/Extensions/BufferExtensions.cs b/BizHawk.Common/Extensions/BufferExtensions.cs index 55b7998bd1..d47680b5b0 100644 --- a/BizHawk.Common/Extensions/BufferExtensions.cs +++ b/BizHawk.Common/Extensions/BufferExtensions.cs @@ -29,6 +29,7 @@ namespace BizHawk.Common.BufferExtensions writer.WriteLine(); } + /// has an odd number of chars public static void ReadFromHex(this byte[] buffer, string hex) { if (hex.Length % 2 != 0) @@ -43,6 +44,7 @@ namespace BizHawk.Common.BufferExtensions } } + /// can't hold the same number of bytes as public static unsafe void ReadFromHexFast(this byte[] buffer, string hex) { if (buffer.Length * 2 != hex.Length) diff --git a/BizHawk.Common/Extensions/CollectionExtensions.cs b/BizHawk.Common/Extensions/CollectionExtensions.cs index 1ee48a4aa9..fb3763a403 100644 --- a/BizHawk.Common/Extensions/CollectionExtensions.cs +++ b/BizHawk.Common/Extensions/CollectionExtensions.cs @@ -59,7 +59,8 @@ namespace BizHawk.Common.CollectionExtensions return mid; } - // http://stackoverflow.com/questions/1766328/can-linq-use-binary-search-when-the-collection-is-ordered + /// not found after mapping over + /// implementation from https://stackoverflow.com/a/1766369/7467292 public static T BinarySearch(this IList list, Func keySelector, TKey key) where TKey : IComparable { diff --git a/BizHawk.Common/Extensions/ReflectionExtensions.cs b/BizHawk.Common/Extensions/ReflectionExtensions.cs index 85bda2ec4a..82733cc009 100644 --- a/BizHawk.Common/Extensions/ReflectionExtensions.cs +++ b/BizHawk.Common/Extensions/ReflectionExtensions.cs @@ -81,10 +81,11 @@ namespace BizHawk.Common.ReflectionExtensions /// /// Gets an enum from a description attribute /// - /// The type of the enum /// The description attribute value + /// The type of the enum /// An enum value with the given description attribute, if no suitable description is found then a default value of the enum is returned - /// http://stackoverflow.com/questions/4367723/get-enum-from-description-attribute + /// does not inherit + /// implementation from https://stackoverflow.com/a/4367868/7467292 public static T GetEnumFromDescription(this string description) { var type = typeof(T); diff --git a/BizHawk.Common/HawkFile.cs b/BizHawk.Common/HawkFile.cs index 0e2c78c3e6..42ccc0b2d0 100644 --- a/BizHawk.Common/HawkFile.cs +++ b/BizHawk.Common/HawkFile.cs @@ -111,22 +111,13 @@ namespace BizHawk.Common /// public bool IsArchiveMember => IsArchive && IsBound; - public IList ArchiveItems - { - get - { - if (!IsArchive) - { - throw new InvalidOperationException("Cant get archive items from non-archive"); - } + /// is + public IList ArchiveItems => IsArchive + ? _archiveItems + : throw new InvalidOperationException("Cant get archive items from non-archive"); - return _archiveItems; - } - } - - /// - /// returns a stream for the currently bound file - /// + /// a stream for the currently bound file + /// no stream bound (haven't called or overload) public Stream GetStream() { if (_boundStream == null) @@ -151,9 +142,8 @@ namespace BizHawk.Common return file.Exists; } - /// - /// Utility: attempts to read all the content from the provided path. - /// + /// reads all the contents of the file at + /// could not find public static byte[] ReadAllBytes(string path) { using var file = new HawkFile(path); @@ -204,9 +194,8 @@ namespace BizHawk.Common _rootPath = path; } - /// - /// Parses the given filename and then opens it. This may take a while (the archive may be accessed and scanned). - /// + /// Opens the file at . This may take a while if the file is an archive, as it may be accessed and scanned. + /// already opened via , this method, or public void Open(string path) { if (_rootPath != null) @@ -308,9 +297,8 @@ namespace BizHawk.Common return BindArchiveMember(ai); } - /// - /// binds the selected archive index - /// + /// binds the selected archive index + /// stream already bound public HawkFile BindArchiveMember(int index) { if (!_rootExists) @@ -383,6 +371,7 @@ namespace BizHawk.Common return BindByExtensionCore(true, extensions); } + /// stream already bound private HawkFile BindByExtensionCore(bool first, params string[] extensions) { if (!_rootExists) diff --git a/BizHawk.Common/IImportResolver.cs b/BizHawk.Common/IImportResolver.cs index 86a2196d44..1e5ad2992a 100644 --- a/BizHawk.Common/IImportResolver.cs +++ b/BizHawk.Common/IImportResolver.cs @@ -12,6 +12,8 @@ namespace BizHawk.Common public interface IImportResolver { IntPtr? GetProcAddrOrNull(string entryPoint); + + /// could not find symbol IntPtr GetProcAddrOrThrow(string entryPoint); } @@ -117,6 +119,6 @@ namespace BizHawk.Common return null; } - public IntPtr GetProcAddrOrThrow(string entryPoint) => GetProcAddrOrNull(entryPoint) ?? throw new IOException($"{entryPoint} was not found in any of the aggregated resolvers"); + public IntPtr GetProcAddrOrThrow(string entryPoint) => GetProcAddrOrNull(entryPoint) ?? throw new InvalidOperationException($"{entryPoint} was not found in any of the aggregated resolvers"); } } diff --git a/BizHawk.Common/MutableIntRange.cs b/BizHawk.Common/MutableIntRange.cs index c9c0a4c260..227e15b362 100644 --- a/BizHawk.Common/MutableIntRange.cs +++ b/BizHawk.Common/MutableIntRange.cs @@ -7,6 +7,7 @@ namespace BizHawk.Common private int _min; private int _max; + /// (from setter) > public int Min { get => _min; @@ -17,6 +18,7 @@ namespace BizHawk.Common } } + /// (from setter) < public int Max { get => _max; @@ -30,7 +32,7 @@ namespace BizHawk.Common public MutableIntRange(int min, int max) { _min = min; - Max = max; // setter may throw ArgumentException + Max = max; // set property instead of field to validate and possibly throw an ArgumentException } public int Constrain(int i) => i < _min ? _min : i > _max ? _max : i; diff --git a/BizHawk.Common/OSTailoredCode.cs b/BizHawk.Common/OSTailoredCode.cs index 29a29621ef..f2188f05b9 100644 --- a/BizHawk.Common/OSTailoredCode.cs +++ b/BizHawk.Common/OSTailoredCode.cs @@ -31,9 +31,15 @@ namespace BizHawk.Common public interface ILinkedLibManager { int FreeByPtr(IntPtr hModule); + IntPtr? GetProcAddrOrNull(IntPtr hModule, string procName); + + /// could not find symbol IntPtr GetProcAddrOrThrow(IntPtr hModule, string procName); + IntPtr? LoadOrNull(string dllToLoad); + + /// could not find library IntPtr LoadOrThrow(string dllToLoad); } @@ -142,7 +148,7 @@ namespace BizHawk.Common /// POSIX $* (space-delimited) /// used in exception /// first line of stdout - /// thrown if stdout is empty + /// stdout is empty /// OS is implicit and needs to be checked at callsite public static string SimpleSubshell(string cmd, string args, string noOutputMsg) { diff --git a/BizHawk.Common/QuickCollections.cs b/BizHawk.Common/QuickCollections.cs index 8f15e653e4..84ed14f453 100644 --- a/BizHawk.Common/QuickCollections.cs +++ b/BizHawk.Common/QuickCollections.cs @@ -52,6 +52,7 @@ namespace BizHawk.Common public int Count => size; + /// called while at capacity public void Enqueue(T item) { if (size >= buffer.Length) @@ -76,6 +77,7 @@ namespace BizHawk.Common return ret; } + /// called while empty public T Dequeue() { if (size == 0) @@ -117,6 +119,7 @@ namespace BizHawk.Common dict = dictionary; } + /// always public void Add(TKey key, TValue value) { throw new InvalidOperationException(); @@ -129,6 +132,7 @@ namespace BizHawk.Common public ICollection Keys => dict.Keys; + /// always public bool Remove(TKey key) { throw new InvalidOperationException(); @@ -141,17 +145,20 @@ namespace BizHawk.Common public ICollection Values => dict.Values; + /// (from setter) always public TValue this[TKey key] { get => dict[key]; set => throw new InvalidOperationException(); } + /// always public void Add(KeyValuePair item) { throw new InvalidOperationException(); } + /// always public void Clear() { throw new InvalidOperationException(); @@ -171,6 +178,7 @@ namespace BizHawk.Common public bool IsReadOnly => true; + /// always public bool Remove(KeyValuePair item) { throw new InvalidOperationException(); diff --git a/BizHawk.Common/Serializer.cs b/BizHawk.Common/Serializer.cs index 2e94f0643b..ff40e99606 100644 --- a/BizHawk.Common/Serializer.cs +++ b/BizHawk.Common/Serializer.cs @@ -128,6 +128,7 @@ namespace BizHawk.Common } } + /// does not inherit public void SyncEnum(string name, ref T val) where T : struct { if (typeof(T).BaseType != typeof(Enum)) @@ -707,6 +708,7 @@ namespace BizHawk.Common } } + /// is and is longer than chars public void SyncFixedString(string name, ref string val, int length) { // TODO - this could be made more efficient perhaps just by writing values right out of the string.. diff --git a/BizHawk.Common/SwitcherStream.cs b/BizHawk.Common/SwitcherStream.cs index 8383bcf8ae..4c74fed67b 100644 --- a/BizHawk.Common/SwitcherStream.cs +++ b/BizHawk.Common/SwitcherStream.cs @@ -28,6 +28,7 @@ namespace BizHawk.Common public override long Length => _currStream.Length; + /// (from setter) is and is not 0 public override long Position { get => _currStream.Position; @@ -57,6 +58,7 @@ namespace BizHawk.Common return _currStream.Read(buffer, offset, count); } + /// is and either is not 0 or is not public override long Seek(long offset, SeekOrigin origin) { if (DenySeekHack) diff --git a/BizHawk.Common/TempFileManager.cs b/BizHawk.Common/TempFileManager.cs index 5c899fbb21..c4afb4d8a8 100644 --- a/BizHawk.Common/TempFileManager.cs +++ b/BizHawk.Common/TempFileManager.cs @@ -28,6 +28,7 @@ namespace BizHawk.Common return Path.Combine(Path.GetTempPath(), fname); } + /// filename in is not one generated by public static string RenameTempFilenameForDelete(string path) { string filename = Path.GetFileName(path); diff --git a/BizHawk.Common/Util.cs b/BizHawk.Common/Util.cs index bbc6debdd7..518e3f4593 100644 --- a/BizHawk.Common/Util.cs +++ b/BizHawk.Common/Util.cs @@ -89,7 +89,8 @@ namespace BizHawk.Common return TryWaitForFileToVanish(pathWant); } - // Could be extension method + /// has an odd number of chars or contains a char not in [0-9A-Fa-f] + /// could be extension method public static byte[] HexStringToBytes(string str) { var ms = new MemoryStream(); @@ -421,6 +422,7 @@ namespace BizHawk.Common return true; } + /// issues with parsing public static byte[] DecompressGzipFile(Stream src) { var tmp = new byte[4];