From 273c0c77440a590b00e370eb9436cbbd46e85adb Mon Sep 17 00:00:00 2001 From: thinker227 Date: Wed, 27 Dec 2023 15:59:17 +0100 Subject: [PATCH] Add more docs --- src/Rascal/Error.cs | 11 ++++++++++ src/Rascal/Result.cs | 3 +++ src/Rascal/ResultExtensions.cs | 2 ++ src/Rascal/Result_Equality.cs | 38 +++++++++++++++++++++++++++++++++- src/Rascal/Result_Mapping.cs | 1 + src/Rascal/Result_Matching.cs | 2 +- src/Rascal/Result_Utility.cs | 28 ++++++++++++++++++++++--- 7 files changed, 80 insertions(+), 5 deletions(-) diff --git a/src/Rascal/Error.cs b/src/Rascal/Error.cs index d36858a..ebf0df5 100644 --- a/src/Rascal/Error.cs +++ b/src/Rascal/Error.cs @@ -24,6 +24,7 @@ public static implicit operator Error(string message) => /// The message to display. public sealed class StringError(string message) : Error { + /// public override string Message => message; /// @@ -38,6 +39,9 @@ public sealed class StringError(string message) : Error /// The exception in the error. public sealed class ExceptionError(Exception exception) : Error { + /// + /// The exception in the error. + /// public Exception Exception { get; } = exception; /// @@ -57,6 +61,7 @@ public sealed class AggregateError(IEnumerable errors) : Error /// public IReadOnlyCollection Errors { get; } = errors.ToList(); + /// public override string Message => string.Join("\n", Errors.Select(x => x.Message)); } @@ -66,6 +71,7 @@ public sealed class AggregateError(IEnumerable errors) : Error /// A message which describes the thing which wasn't found. public sealed class NotFoundError(string message) : Error { + /// public override string Message => message; } @@ -75,6 +81,7 @@ public sealed class NotFoundError(string message) : Error /// An optional message describing the operation and why it is invalid. public sealed class InvalidOperationError(string? message = null) : Error { + /// public override string Message => message ?? "Invalid operation."; } @@ -84,6 +91,7 @@ public sealed class InvalidOperationError(string? message = null) : Error /// An optional message describing the thing which is . public sealed class NullError(string? message = null) : Error { + /// public override string Message => message ?? "Value is null."; } @@ -99,6 +107,7 @@ public sealed class ValidationError(string message, object? source) : Error /// public object? Source => source; + /// public override string Message => message; } @@ -114,6 +123,7 @@ public sealed class ParseError(string message, object? source) : Error /// public object? Source => source; + /// public override string Message => message; } @@ -123,5 +133,6 @@ public sealed class ParseError(string message, object? source) : Error /// The optional message describing the task cancellation. public sealed class CancellationError(string? message = null) : Error { + /// public override string Message => message ?? "Task was cancelled."; } diff --git a/src/Rascal/Result.cs b/src/Rascal/Result.cs index 7de25cb..5658957 100644 --- a/src/Rascal/Result.cs +++ b/src/Rascal/Result.cs @@ -41,6 +41,9 @@ public Result(Error error) this.error = error; } + /// + /// Gets a string representation of the result. + /// [Pure] public override string ToString() => HasValue diff --git a/src/Rascal/ResultExtensions.cs b/src/Rascal/ResultExtensions.cs index cc133cc..959f80a 100644 --- a/src/Rascal/ResultExtensions.cs +++ b/src/Rascal/ResultExtensions.cs @@ -100,6 +100,7 @@ public static Result> Sequence(this IEnumerable> r /// The type of values in the dictionary. /// The dictionary to try locate the key in. /// The key to locate. + /// The error to return if the key is not present. /// A result containing the value associated with in the dictionary, /// or an error if the key is not present. public static Result TryGetValueR( @@ -118,6 +119,7 @@ public static Result TryGetValueR( /// The type of the elements in the list. /// The list to index. /// The zero-based index of the element to get. + /// The error to return if the index is out of range. /// A result containing the value at in the list, /// or an error if the index is out of range of the list. public static Result Index(this IReadOnlyList list, int index, Error? error = null) => diff --git a/src/Rascal/Result_Equality.cs b/src/Rascal/Result_Equality.cs index 007be82..0fbdef9 100644 --- a/src/Rascal/Result_Equality.cs +++ b/src/Rascal/Result_Equality.cs @@ -9,38 +9,74 @@ namespace Rascal; System.Numerics.IEqualityOperators, T, bool> #endif { + /// + /// Checks whether the result has a value and the value is equal to another value. + /// + /// The value to check for equality with the value in the result. [Pure] public bool Equals(T? other) => HasValue && (other?.Equals(value) ?? value is null); + /// + /// Checks whether the result is equal to another result. + /// Results are equal if both results have values which are equal, + /// or if both results are errors. + /// + /// The result to check for equality with the current result. [Pure] public bool Equals(Result other) => HasValue && other.HasValue && (other.value?.Equals(value) ?? value is null) || !HasValue && !other.HasValue; + /// [Pure] public override bool Equals(object? other) => other is T x && Equals(x) || other is Result r && Equals(r); + /// [Pure] public override int GetHashCode() => HasValue ? value?.GetHashCode() ?? 0 : 0; + /// + /// Checks whether two results are equal. + /// Results are equal if both results have values which are equal, + /// or if both results are errors. + /// + /// The first result to compare. + /// The second result to compare. [Pure] public static bool operator ==(Result a, Result b) => a.Equals(b); + /// + /// Checks whether two results are not equal. + /// Results are equal if both results have values which are equal, + /// or if both results are errors. + /// + /// The first result to compare. + /// The second result to compare. [Pure] public static bool operator !=(Result a, Result b) => !a.Equals(b); + /// + /// Checks whether a result has a value and the value is equal to another value. + /// + /// The result to compare. + /// The value to check for equality with the value in the result. [Pure] public static bool operator ==(Result a, T? b) => a.Equals(b); - + + /// + /// Checks whether a result either does not have a value, or the value is not equal to another value. + /// + /// The result to compare. + /// The value to check for inequality with the value in the result. [Pure] public static bool operator !=(Result a, T? b) => !a.Equals(b); diff --git a/src/Rascal/Result_Mapping.cs b/src/Rascal/Result_Mapping.cs index d029c6d..fbc41dc 100644 --- a/src/Rascal/Result_Mapping.cs +++ b/src/Rascal/Result_Mapping.cs @@ -49,6 +49,7 @@ public Result SelectMany(Func> mapping) => /// The expression r.SelectMany(x => f(x), (x, y) => g(x, y)) can be written as /// r.Bind(x => f(x).Map(y => g(x, y))). /// + /// The function used to map the value to an intermediate result. /// The function used to map the value to a new result. /// The type of the intermediate value. /// The type of the new value. diff --git a/src/Rascal/Result_Matching.cs b/src/Rascal/Result_Matching.cs index 9e99d7b..448522e 100644 --- a/src/Rascal/Result_Matching.cs +++ b/src/Rascal/Result_Matching.cs @@ -140,7 +140,7 @@ public T GetValueOrDefault(T @default) => /// Gets the value within the result, /// or a default value if the result does not contain a value. /// - /// A function to get a default value to return + /// A function to get a default value to return /// if the result does not contain a value. [Pure] public T GetValueOrDefault(Func getDefault) => diff --git a/src/Rascal/Result_Utility.cs b/src/Rascal/Result_Utility.cs index 226b999..3934f12 100644 --- a/src/Rascal/Result_Utility.cs +++ b/src/Rascal/Result_Utility.cs @@ -51,6 +51,7 @@ public Result ToType(string? error = null) value)) : new(Error); +#if NETCOREAPP /// /// Checks whether the value in the result matches a predicate, /// and if not replaces the value with an error. @@ -65,12 +66,23 @@ public Result ToType(string? error = null) /// error produced by . /// If the original result does not contain a value, that result will be returned. [Pure] -#if NETCOREAPP public Result Validate( Func predicate, Func? getError = null, [CallerArgumentExpression(nameof(predicate))] string expr = "") => #else + /// + /// Checks whether the value in the result matches a predicate, + /// and if not replaces the value with an error. + /// + /// The predicate to match the value against. + /// A function to produce an error + /// if the value doesn't match the predicate. + /// A result which contains the value of the original result + /// if the value matches , otherwise an + /// error produced by . + /// If the original result does not contain a value, that result will be returned. + [Pure] public Result Validate( Func predicate, Func? getError = null) => @@ -86,6 +98,7 @@ public Result Validate( #endif : new(Error); +#if NETCOREAPP /// /// Checks whether the value in the result matches a predicate, /// and if not replaces the value with an error. @@ -98,13 +111,22 @@ public Result Validate( /// If the original result does not contain a value, that result will be returned. [Pure] public Result Where( -#if NETCOREAPP Func predicate, [CallerArgumentExpression(nameof(predicate))] string expr = "") => Validate(predicate, null, expr); #else + /// + /// Checks whether the value in the result matches a predicate, + /// and if not replaces the value with an error. + /// + /// The predicate to match the value against. + /// A result which contains the value of the original result + /// if the value matches , otherwise an error. + /// If the original result does not contain a value, that result will be returned. + [Pure] + public Result Where( Func predicate) => - Validate(predicate, null); + Validate(predicate); #endif ///