ShuriZma
/
BizHawk
mirror of https://github.com/TASEmulators/BizHawk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve exception docs in BizHawk.Common

This commit is contained in:
YoshiRulz 2019-12-28 05:41:54 +10:00
parent 8c0c00c2bf
commit 19705b78fd
No known key found for this signature in database
GPG Key ID: C4DE31C245353FB7
19 changed files with 72 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
BizHawk.Common/AWEMemoryStream.cs
View File

@ -383,6 +383,7 @@ namespace BizHawk.Common
}
}
/// <exception cref="InvalidOperationException"><paramref name="byteSize"/> is equivalent to more than <see cref="UInt32.MaxValue">uint.MaxValue</see> pages</exception>
public bool Allocate(int byteSize)
{
if (!TryAcquirePrivilege())

2
BizHawk.Common/BizInvoke/BizInvoker.cs
View File

@ -60,6 +60,7 @@ namespace BizHawk.Common.BizInvoke
/// get an implementation proxy for an interop class
/// </summary>
/// <typeparam name="T">The class type that represents the DLL</typeparam>
/// <exception cref="InvalidOperationException"><see cref="GetInvoker{T}(BizHawk.Common.IImportResolver,BizHawk.Common.IMonitor,BizHawk.Common.BizInvoke.ICallingConventionAdapter)"/> previously called with <paramref name="dll"/></exception>
public static T GetInvoker<T>(IImportResolver dll, ICallingConventionAdapter adapter)
where T : class
{
@ -82,6 +83,7 @@ namespace BizHawk.Common.BizInvoke
return (T)impl.Create(dll, null, adapter);
}
/// <exception cref="InvalidOperationException">this method was previously called with <paramref name="dll"/></exception>
public static T GetInvoker<T>(IImportResolver dll, IMonitor monitor, ICallingConventionAdapter adapter)
where T : class
{

1
BizHawk.Common/BizInvoke/CallingConventionAdapter.cs
View File

@ -38,6 +38,7 @@ namespace BizHawk.Common.BizInvoke
ParameterTypes = parameterTypes.ToList().AsReadOnly();
}
/// <exception cref="InvalidOperationException"><paramref name="delegateType"/> does not inherit <see cref="Delegate"/></exception>
public ParameterInfo(Type delegateType)
{
if (!typeof(Delegate).IsAssignableFrom(delegateType))

10
BizHawk.Common/BizInvoke/MemoryBlock.cs
View File

@ -11,9 +11,8 @@ namespace BizHawk.Common.BizInvoke
/// </summary>
private IntPtr _handle;
/// <summary>
/// allocate size bytes starting at a particular address
/// </summary>
/// <summary>allocate <paramref name="size"/> bytes starting at a particular address <paramref name="start"/></summary>
/// <exception cref="InvalidOperationException">failed to create file mapping</exception>
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");
}
/// <exception cref="InvalidOperationException"><see cref="MemoryBlockBase.Active"/> is <see langword="true"/> or failed to map file view</exception>
public override void Activate()
{
if (Active)
@ -40,6 +40,7 @@ namespace BizHawk.Common.BizInvoke
Active = true;
}
/// <exception cref="InvalidOperationException"><see cref="MemoryBlockBase.Active"/> is <see langword="false"/> or failed to unmap file view</exception>
public override void Deactivate()
{
if (!Active)
@ -49,6 +50,7 @@ namespace BizHawk.Common.BizInvoke
Active = false;
}
/// <exception cref="InvalidOperationException">snapshot already taken, <see cref="MemoryBlockBase.Active"/> is <see langword="false"/>, or failed to make memory read-only</exception>
public override void SaveXorSnapshot()
{
if (_snapshot != null)
@ -71,6 +73,7 @@ namespace BizHawk.Common.BizInvoke
ProtectAll();
}
/// <exception cref="InvalidOperationException"><see cref="MemoryBlockBase.Active"/> is <see langword="false"/> or failed to make memory read-only</exception>
public override byte[] FullHash()
{
if (!Active)
@ -116,6 +119,7 @@ namespace BizHawk.Common.BizInvoke
}
}
/// <exception cref="InvalidOperationException">failed to protect memory</exception>
public override void Protect(ulong start, ulong length, Protection prot)
{
if (length == 0)

3
BizHawk.Common/BizInvoke/MemoryBlockBase.cs
View File

@ -47,6 +47,7 @@ namespace BizHawk.Common.BizInvoke
protected ulong GetStartAddr(int page) => ((ulong) page << WaterboxUtils.PageShift) + Start;
/// <summary>Get a stream that can be used to read or write from part of the block. Does not check for or change <see cref="Protect"/>!</summary>
/// <exception cref="ArgumentOutOfRangeException"><paramref name="start"/> or end (= <paramref name="start"/> + <paramref name="length"/>) are outside bounds of memory block (<see cref="Start"/> and <see cref="End"/>)</exception>
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
}
/// <summary>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</summary>
/// <exception cref="ArgumentOutOfRangeException"><paramref name="start"/> or end (= <paramref name="start"/> + <paramref name="length"/>) are outside bounds of memory block (<see cref="Start"/> and <see cref="End"/>)</exception>
/// <exception cref="InvalidOperationException">no snapshot taken (haven't called <see cref="SaveXorSnapshot"/>)</exception>
public Stream GetXorStream(ulong start, ulong length, bool writer)
{
if (start < Start) throw new ArgumentOutOfRangeException(nameof(start));

7
BizHawk.Common/BizInvoke/MemoryBlockUnix.cs
View File

@ -11,6 +11,8 @@ namespace BizHawk.Common.BizInvoke
private int _fd;
/// <summary>allocate <paramref name="size"/> bytes starting at a particular address <paramref name="start"/></summary>
/// <exception cref="InvalidOperationException">failed to get file descriptor (never thrown as <see cref="NotImplementedException"/> is thrown first)</exception>
/// <exception cref="NotImplementedException">always</exception>
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");
}
/// <exception cref="InvalidOperationException"><see cref="MemoryBlockBase.Active"/> is <see langword="true"/> or failed to map memory</exception>
public override void Activate()
{
if (Active) throw new InvalidOperationException("Already active");
@ -29,6 +32,7 @@ namespace BizHawk.Common.BizInvoke
Active = true;
}
/// <exception cref="InvalidOperationException"><see cref="MemoryBlockBase.Active"/> is <see langword="false"/> or failed to unmap memory</exception>
public override void Deactivate()
{
if (!Active) throw new InvalidOperationException("Not active");
@ -39,6 +43,7 @@ namespace BizHawk.Common.BizInvoke
Active = false;
}
/// <exception cref="InvalidOperationException"><see cref="MemoryBlockBase.Active"/> is <see langword="false"/> or failed to make memory read-only</exception>
public override byte[] FullHash()
{
if (!Active) throw new InvalidOperationException("Not active");
@ -52,6 +57,7 @@ namespace BizHawk.Common.BizInvoke
return ret;
}
/// <exception cref="InvalidOperationException">failed to protect memory</exception>
public override void Protect(ulong start, ulong length, Protection prot)
{
if (length == 0) return;
@ -92,6 +98,7 @@ namespace BizHawk.Common.BizInvoke
}
}
/// <exception cref="InvalidOperationException">snapshot already taken, <see cref="MemoryBlockBase.Active"/> is <see langword="false"/>, or failed to make memory read-only</exception>
public override void SaveXorSnapshot()
{
if (_snapshot != null) throw new InvalidOperationException("Snapshot already taken");

5
BizHawk.Common/DeepEquality.cs
View File

@ -51,9 +51,8 @@ namespace BizHawk.Common
static MethodInfo ArrayEqualsGeneric = typeof(DeepEquality).GetMethod("ArrayEquals", BindingFlags.NonPublic | BindingFlags.Static);
/// <summary>
/// test if two objects are equal field by field (with deep inspection of each field)
/// </summary>
/// <summary>test if two objects <paramref name="o1"/> and <paramref name="o2"/> are equal, field-by-field (with deep inspection of each field)</summary>
/// <exception cref="InvalidOperationException"><paramref name="o1"/> is an array with rank > 1 or is a non-zero-indexed array</exception>
public static bool DeepEquals(object o1, object o2)
{
if (o1 == o2)

2
BizHawk.Common/Extensions/BufferExtensions.cs
View File

@ -29,6 +29,7 @@ namespace BizHawk.Common.BufferExtensions
writer.WriteLine();
}
/// <exception cref="Exception"><paramref name="hex"/> has an odd number of chars</exception>
public static void ReadFromHex(this byte[] buffer, string hex)
{
if (hex.Length % 2 != 0)
@ -43,6 +44,7 @@ namespace BizHawk.Common.BufferExtensions
}
}
/// <exception cref="Exception"><paramref name="buffer"/> can't hold the same number of bytes as <paramref name="hex"/></exception>
public static unsafe void ReadFromHexFast(this byte[] buffer, string hex)
{
if (buffer.Length * 2 != hex.Length)

3
BizHawk.Common/Extensions/CollectionExtensions.cs
View File

@ -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
/// <exception cref="InvalidOperationException"><paramref name="key"/> not found after mapping <paramref name="keySelector"/> over <paramref name="list"/></exception>
/// <remarks>implementation from https://stackoverflow.com/a/1766369/7467292</remarks>
public static T BinarySearch<T, TKey>(this IList<T> list, Func<T, TKey> keySelector, TKey key)
where TKey : IComparable<TKey>
{

5
BizHawk.Common/Extensions/ReflectionExtensions.cs
View File

@ -81,10 +81,11 @@ namespace BizHawk.Common.ReflectionExtensions
/// <summary>
/// Gets an enum from a description attribute
/// </summary>
/// <typeparam name="T">The type of the enum</typeparam>
/// <param name="description">The description attribute value</param>
/// <typeparam name="T">The type of the enum</typeparam>
/// <returns>An enum value with the given description attribute, if no suitable description is found then a default value of the enum is returned</returns>
/// <remarks>http://stackoverflow.com/questions/4367723/get-enum-from-description-attribute</remarks>
/// <exception cref="InvalidOperationException"><typeparamref name="T"/> does not inherit <see cref="Enum"/></exception>
/// <remarks>implementation from https://stackoverflow.com/a/4367868/7467292</remarks>
public static T GetEnumFromDescription<T>(this string description)
{
var type = typeof(T);

37
BizHawk.Common/HawkFile.cs
View File

@ -111,22 +111,13 @@ namespace BizHawk.Common
/// </summary>
public bool IsArchiveMember => IsArchive && IsBound;
public IList<HawkFileArchiveItem> ArchiveItems
{
get
{
if (!IsArchive)
{
throw new InvalidOperationException("Cant get archive items from non-archive");
}
/// <exception cref="InvalidOperationException"><see cref="IsArchive"/> is <see langword="false"/></exception>
public IList<HawkFileArchiveItem> ArchiveItems => IsArchive
? _archiveItems
: throw new InvalidOperationException("Cant get archive items from non-archive");
return _archiveItems;
}
}
/// <summary>
/// returns a stream for the currently bound file
/// </summary>
/// <returns>a stream for the currently bound file</returns>
/// <exception cref="InvalidOperationException">no stream bound (haven't called <see cref="BindArchiveMember(int)"/> or overload)</exception>
public Stream GetStream()
{
if (_boundStream == null)
@ -151,9 +142,8 @@ namespace BizHawk.Common
return file.Exists;
}
/// <summary>
/// Utility: attempts to read all the content from the provided path.
/// </summary>
/// <summary>reads all the contents of the file at <paramref name="path"/></summary>
/// <exception cref="FileNotFoundException">could not find <paramref name="path"/></exception>
public static byte[] ReadAllBytes(string path)
{
using var file = new HawkFile(path);
@ -204,9 +194,8 @@ namespace BizHawk.Common
_rootPath = path;
}
/// <summary>
/// Parses the given filename and then opens it. This may take a while (the archive may be accessed and scanned).
/// </summary>
/// <summary>Opens the file at <paramref name="path"/>. This may take a while if the file is an archive, as it may be accessed and scanned.</summary>
/// <exception cref="InvalidOperationException">already opened via <see cref="HawkFile(string)"/>, this method, or <see cref="Parse"/></exception>
public void Open(string path)
{
if (_rootPath != null)
@ -308,9 +297,8 @@ namespace BizHawk.Common
return BindArchiveMember(ai);
}
/// <summary>
/// binds the selected archive index
/// </summary>
/// <summary>binds the selected archive index</summary>
/// <exception cref="InvalidOperationException">stream already bound</exception>
public HawkFile BindArchiveMember(int index)
{
if (!_rootExists)
@ -383,6 +371,7 @@ namespace BizHawk.Common
return BindByExtensionCore(true, extensions);
}
/// <exception cref="InvalidOperationException">stream already bound</exception>
private HawkFile BindByExtensionCore(bool first, params string[] extensions)
{
if (!_rootExists)

4
BizHawk.Common/IImportResolver.cs
View File

@ -12,6 +12,8 @@ namespace BizHawk.Common
public interface IImportResolver
{
IntPtr? GetProcAddrOrNull(string entryPoint);
/// <exception cref="InvalidOperationException">could not find symbol</exception>
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");
}
}

4
BizHawk.Common/MutableIntRange.cs
View File

@ -7,6 +7,7 @@ namespace BizHawk.Common
private int _min;
private int _max;
/// <exception cref="ArgumentException">(from setter) <paramref name="value"/> > <see cref="Max"/></exception>
public int Min
{
get => _min;
@ -17,6 +18,7 @@ namespace BizHawk.Common
}
}
/// <exception cref="ArgumentException">(from setter) <paramref name="value"/> &lt; <see cref="Min"/></exception>
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;

8
BizHawk.Common/OSTailoredCode.cs
View File

@ -31,9 +31,15 @@ namespace BizHawk.Common
public interface ILinkedLibManager
{
int FreeByPtr(IntPtr hModule);
IntPtr? GetProcAddrOrNull(IntPtr hModule, string procName);
/// <exception cref="InvalidOperationException">could not find symbol</exception>
IntPtr GetProcAddrOrThrow(IntPtr hModule, string procName);
IntPtr? LoadOrNull(string dllToLoad);
/// <exception cref="InvalidOperationException">could not find library</exception>
IntPtr LoadOrThrow(string dllToLoad);
}
@ -142,7 +148,7 @@ namespace BizHawk.Common
/// <param name="args">POSIX <c>$*</c> (space-delimited)</param>
/// <param name="noOutputMsg">used in exception</param>
/// <returns>first line of stdout</returns>
/// <exception cref="Exception">thrown if stdout is empty</exception>
/// <exception cref="Exception">stdout is empty</exception>
/// <remarks>OS is implicit and needs to be checked at callsite</remarks>
public static string SimpleSubshell(string cmd, string args, string noOutputMsg)
{

8
BizHawk.Common/QuickCollections.cs
View File

@ -52,6 +52,7 @@ namespace BizHawk.Common
public int Count => size;
/// <exception cref="Exception">called while at capacity</exception>
public void Enqueue(T item)
{
if (size >= buffer.Length)
@ -76,6 +77,7 @@ namespace BizHawk.Common
return ret;
}
/// <exception cref="Exception">called while empty</exception>
public T Dequeue()
{
if (size == 0)
@ -117,6 +119,7 @@ namespace BizHawk.Common
dict = dictionary;
}
/// <exception cref="InvalidOperationException">always</exception>
public void Add(TKey key, TValue value)
{
throw new InvalidOperationException();
@ -129,6 +132,7 @@ namespace BizHawk.Common
public ICollection<TKey> Keys => dict.Keys;
/// <exception cref="InvalidOperationException">always</exception>
public bool Remove(TKey key)
{
throw new InvalidOperationException();
@ -141,17 +145,20 @@ namespace BizHawk.Common
public ICollection<TValue> Values => dict.Values;
/// <exception cref="InvalidOperationException">(from setter) always</exception>
public TValue this[TKey key]
{
get => dict[key];
set => throw new InvalidOperationException();
}
/// <exception cref="InvalidOperationException">always</exception>
public void Add(KeyValuePair<TKey, TValue> item)
{
throw new InvalidOperationException();
}
/// <exception cref="InvalidOperationException">always</exception>
public void Clear()
{
throw new InvalidOperationException();
@ -171,6 +178,7 @@ namespace BizHawk.Common
public bool IsReadOnly => true;
/// <exception cref="InvalidOperationException">always</exception>
public bool Remove(KeyValuePair<TKey, TValue> item)
{
throw new InvalidOperationException();

2
BizHawk.Common/Serializer.cs
View File

@ -128,6 +128,7 @@ namespace BizHawk.Common
}
}
/// <exception cref="InvalidOperationException"><typeparamref name="T"/> does not inherit <see cref="Enum"/></exception>
public void SyncEnum<T>(string name, ref T val) where T : struct
{
if (typeof(T).BaseType != typeof(Enum))
@ -707,6 +708,7 @@ namespace BizHawk.Common
}
}
/// <exception cref="InvalidOperationException"><see cref="IsReader"/> is <see langword="false"/> and <paramref name="name"/> is longer than <paramref name="length"/> chars</exception>
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..

2
BizHawk.Common/SwitcherStream.cs
View File

@ -28,6 +28,7 @@ namespace BizHawk.Common
public override long Length => _currStream.Length;
/// <exception cref="InvalidOperationException">(from setter) <see cref="DenySeekHack"/> is <see langword="true"/> and <paramref name="value"/> is not <c>0</c></exception>
public override long Position
{
get => _currStream.Position;
@ -57,6 +58,7 @@ namespace BizHawk.Common
return _currStream.Read(buffer, offset, count);
}
/// <exception cref="InvalidOperationException"><see cref="DenySeekHack"/> is <see langword="true"/> and either <paramref name="value"/> is not <c>0</c> or <paramref name="origin"/> is not <see cref="SeekOrigin.Begin"/></exception>
public override long Seek(long offset, SeekOrigin origin)
{
if (DenySeekHack)

1
BizHawk.Common/TempFileManager.cs
View File

@ -28,6 +28,7 @@ namespace BizHawk.Common
return Path.Combine(Path.GetTempPath(), fname);
}
/// <exception cref="InvalidOperationException">filename in <paramref name="path"/> is not one generated by <see cref="GetTempFilename"/></exception>
public static string RenameTempFilenameForDelete(string path)
{
string filename = Path.GetFileName(path);

4
BizHawk.Common/Util.cs
View File

@ -89,7 +89,8 @@ namespace BizHawk.Common
return TryWaitForFileToVanish(pathWant);
}
// Could be extension method
/// <exception cref="ArgumentException"><paramref name="str"/> has an odd number of chars or contains a char not in <c>[0-9A-Fa-f]</c></exception>
/// <remarks>could be extension method</remarks>
public static byte[] HexStringToBytes(string str)
{
var ms = new MemoryStream();
@ -421,6 +422,7 @@ namespace BizHawk.Common
return true;
}
/// <exception cref="InvalidOperationException">issues with parsing <paramref name="src"/></exception>
public static byte[] DecompressGzipFile(Stream src)
{
var tmp = new byte[4];