documentation(Result): improve readability of parameters

daht-x · Jun 12, 2024 · b0a91a4 · b0a91a4
1 parent 8a3cb25
commit b0a91a4
Show file tree

Hide file tree

Showing 2 changed files with 67 additions and 67 deletions.
diff --git a/libraries/core/documentation/monads/result.md b/libraries/core/documentation/monads/result.md
@@ -60,7 +60,7 @@ Type of expected success.
 - Declaration
 
   ```cs
-  public bool IsFailed { get; }
+  public bool IsFailed
   ```
 
 - Description: Indicates whether the status is failed.
@@ -72,7 +72,7 @@ Type of expected success.
 - Declaration
 
   ```cs
-  public TFailure Failure { get; }
+  public TFailure Failure
   ```
 
 - Description: The possible failure.
@@ -84,7 +84,7 @@ Type of expected success.
 - Declaration
 
   ```cs
-  public bool IsSuccessful { get; }
+  public bool IsSuccessful
   ```
 
 - Description: Indicates whether the status is successful.
@@ -96,7 +96,7 @@ Type of expected success.
 - Declaration
 
   ```cs
-  public TSuccess Success { get; }
+  public TSuccess Success
   ```
 
 - Description: The expected success.
@@ -115,9 +115,9 @@ Type of expected success.
 
 - Description: Creates a new failed result.
 - Parameters:
-  | Name      | Description          |
-  |:----------|:---------------------|
-  | `failure` | The possible failure |
+  | Name      | Description        |
+  |:----------|:-------------------|
+  | `failure` | A possible failure |
 
 ***[Top](#resulttfailure-tsuccess)***
 
@@ -131,9 +131,9 @@ Type of expected success.
 
 - Description: Creates a new successful result.
 - Parameters:
-  | Name      | Description          |
-  |:----------|:---------------------|
-  | `success` | The expected success |
+  | Name      | Description         |
+  |:----------|:--------------------|
+  | `success` | An expected success |
 
 ***[Top](#resulttfailure-tsuccess)***
 
@@ -149,9 +149,9 @@ Type of expected success.
 
 - Description: Creates a new failed result.
 - Parameters:
-  | Name      | Description          |
-  |:----------|:---------------------|
-  | `failure` | The possible failure |
+  | Name      | Description        |
+  |:----------|:-------------------|
+  | `failure` | A possible failure |
 
 ***[Top](#resulttfailure-tsuccess)***
 
@@ -165,15 +165,15 @@ Type of expected success.
 
 - Description: Creates a new successful result.
 - Parameters:
-  | Name      | Description          |
-  |:----------|:---------------------|
-  | `success` | The expected success |
+  | Name      | Description         |
+  |:----------|:--------------------|
+  | `success` | An expected success |
 
 ***[Top](#resulttfailure-tsuccess)***
 
 ### Methods
 
-### `Catch<TException>(execute, createFailure`
+#### `Catch<TException>(execute, createFailure`
 
 - Declaration:
 
@@ -188,10 +188,10 @@ Type of expected success.
   |:-------------|:---------------------------|
   | `TException` | Type of possible exception |
 - Parameters:
-  | Name            | Description                  |
-  |:----------------|:-----------------------------|
-  | `execute`       | The action to execute        |
-  | `createFailure` | Creates the possible failure |
+  | Name            | Description                |
+  |:----------------|:---------------------------|
+  | `execute`       | The action to execute      |
+  | `createFailure` | Creates a possible failure |
 
 ***[Top](#resulttfailure-tsuccess)***
 
@@ -211,10 +211,10 @@ successful result.
   |:-------------|:---------------------------|
   | `TException` | Type of possible exception |
 - Parameters:
-  | Name            | Description                  |
-  |:----------------|:-----------------------------|
-  | `createSuccess` | Creates the expected success |
-  | `createFailure` | Creates the possible failure |
+  | Name            | Description                 |
+  |:----------------|:----------------------------|
+  | `createSuccess` | Creates an expected success |
+  | `createFailure` | Creates a possible failure  |
 
 ***[Top](#resulttfailure-tsuccess)***
 
@@ -231,7 +231,7 @@ successful result.
   | Name        | Description               |
   |:------------|:--------------------------|
   | `predicate` | Creates a set of criteria |
-  | `failure`   | The possible failure      |
+  | `failure`   | A possible failure        |
 
 ***[Top](#resulttfailure-tsuccess)***
 
@@ -245,10 +245,10 @@ successful result.
 
 - Description: Creates a new failed result if the value of `predicate` is `true`; otherwise, returns the previous result.
 - Parameters:
-  | Name            | Description                  |
-  |:----------------|:-----------------------------|
-  | `predicate`     | Creates a set of criteria    |
-  | `createFailure` | Creates the possible failure |
+  | Name            | Description                |
+  |:----------------|:---------------------------|
+  | `predicate`     | Creates a set of criteria  |
+  | `createFailure` | Creates a possible failure |
 
 ***[Top](#resulttfailure-tsuccess)***
 
@@ -266,11 +266,11 @@ successful result.
   |:-------------|:------------------|
   | `TAuxiliary` | Type of auxiliary |
 - Parameters:
-  | Name            | Description                                                              |
-  |:----------------|:-------------------------------------------------------------------------|
-  | `auxiliary`     | The auxiliary to use in combination with `predicate` and `createFailure` |
-  | `predicate`     | Creates a set of criteria                                                |
-  | `createFailure` | Creates the possible failure                                             |
+  | Name            | Description                                                             |
+  |:----------------|:------------------------------------------------------------------------|
+  | `auxiliary`     | An auxiliary to use in combination with `predicate` and `createFailure` |
+  | `predicate`     | Creates a set of criteria                                               |
+  | `createFailure` | Creates a possible failure                                              |
 
 ***[Top](#resulttfailure-tsuccess)***
 
@@ -288,11 +288,11 @@ successful result.
   |:-------------|:------------------|
   | `TAuxiliary` | Type of auxiliary |
 - Parameters:
-  | Name              | Description                                                                      |
-  |:------------------|:---------------------------------------------------------------------------------|
-  | `createAuxiliary` | Creates the auxiliary to use in combination with `predicate` and `createFailure` |
-  | `predicate`       | Creates a set of criteria                                                        |
-  | `createFailure`   | Creates the possible failure                                                     |
+  | Name              | Description                                                                     |
+  |:------------------|:--------------------------------------------------------------------------------|
+  | `createAuxiliary` | Creates an auxiliary to use in combination with `predicate` and `createFailure` |
+  | `predicate`       | Creates a set of criteria                                                       |
+  | `createFailure`   | Creates a possible failure                                                      |
 
 ***[Top](#resulttfailure-tsuccess)***
 
@@ -342,9 +342,9 @@ successful result.
   |:----------------|:--------------------------------|
   | `TSuccessToMap` | Type of expected success to map |
 - Parameters:
-  | Name           | Description                 |
-  |:---------------|:----------------------------|
-  | `successToMap` | The expected success to map |
+  | Name           | Description                |
+  |:---------------|:---------------------------|
+  | `successToMap` | An expected success to map |
 
 ***[Top](#resulttfailure-tsuccess)***
 
@@ -362,9 +362,9 @@ successful result.
   |:----------------|:--------------------------------|
   | `TSuccessToMap` | Type of expected success to map |
 - Parameters:
-  | Name                 | Description                         |
-  |:---------------------|:------------------------------------|
-  | `createSuccessToMap` | Creates the expected success to map |
+  | Name                 | Description                        |
+  |:---------------------|:-----------------------------------|
+  | `createSuccessToMap` | Creates an expected success to map |
 
 ***[Top](#resulttfailure-tsuccess)***
 
@@ -402,10 +402,10 @@ successful result.
   |:-----------|:----------------|
   | `TReducer` | Type of reducer |
 - Parameters:
-  | Name            | Description                          |
-  |:----------------|:-------------------------------------|
-  | `reduceFailure` | Creates the possible reduced failure |
-  | `reduceSuccess` | Creates the expected reduced success |
+  | Name            | Description                         |
+  |:----------------|:------------------------------------|
+  | `reduceFailure` | Creates a possible reduced failure  |
+  | `reduceSuccess` | Creates an expected reduced success |
 
 ***[Top](#resulttfailure-tsuccess)***
 

diff --git a/libraries/core/source/Monads/Result.cs b/libraries/core/source/Monads/Result.cs
@@ -19,36 +19,36 @@ public sealed class Result<TFailure, TSuccess>
 	public TSuccess Success { get; } = default!;
 
 	/// <summary>Creates a new failed result.</summary>
-	/// <param name="failure">The possible failure.</param>
+	/// <param name="failure">A possible failure.</param>
 	public Result(TFailure failure)
 	{
 		IsFailed = true;
 		Failure = failure;
 	}
 
 	/// <summary>Creates a new successful result.</summary>
-	/// <param name="success">The expected success.</param>
+	/// <param name="success">An expected success.</param>
 	public Result(TSuccess success)
 	{
 		IsSuccessful = true;
 		Success = success;
 	}
 
 	/// <summary>Creates a new failed result.</summary>
-	/// <param name="failure">The possible failure.</param>
+	/// <param name="failure">A possible failure.</param>
 	/// <returns>A new failed result.</returns>
 	public static implicit operator Result<TFailure, TSuccess>(TFailure failure)
 		=> new(failure);
 
 	/// <summary>Creates a new successful result.</summary>
-	/// <param name="success">The expected success.</param>
+	/// <param name="success">An expected success.</param>
 	/// <returns>A new successful result.</returns>
 	public static implicit operator Result<TFailure, TSuccess>(TSuccess success)
 		=> new(success);
 
 	/// <summary>Creates a new failed result if <paramref name="execute" /> throws <typeparamref name="TException" />; otherwise, returns the previous result.</summary>
 	/// <param name="execute">The action to execute.</param>
-	/// <param name="createFailure">Creates the possible failure.</param>
+	/// <param name="createFailure">Creates a possible failure.</param>
 	/// <typeparam name="TException">Type of possible exception.</typeparam>
 	/// <returns>A new failed result if <paramref name="execute" /> throws <typeparamref name="TException" />; otherwise, the previous result.</returns>
 	public Result<TFailure, TSuccess> Catch<TException>(Action<TSuccess> execute,
@@ -71,8 +71,8 @@ public Result(TSuccess success)
 	}
 
 	/// <summary>Creates a new failed result if the value of <paramref name="createSuccess" /> throws <typeparamref name="TException" />; otherwise, creates a new successful result.</summary>
-	/// <param name="createSuccess">Creates the expected success.</param>
-	/// <param name="createFailure">Creates the possible failure.</param>
+	/// <param name="createSuccess">Creates an expected success.</param>
+	/// <param name="createFailure">Creates a possible failure.</param>
 	/// <typeparam name="TException">Type of possible exception.</typeparam>
 	/// <returns>A new failed result if the value of <paramref name="createSuccess" /> throws <typeparamref name="TException" />; otherwise, a new successful result.</returns>
 	public Result<TFailure, TSuccess> Catch<TException>(Func<TSuccess, TSuccess> createSuccess,
@@ -93,14 +93,14 @@ public Result(TSuccess success)
 
 	/// <summary>Creates a new failed result if the value of <paramref name="predicate" /> is <see langword="true" />; otherwise, returns the previous result.</summary>
 	/// <param name="predicate">Creates a set of criteria.</param>
-	/// <param name="createFailure">Creates the possible failure.</param>
+	/// <param name="createFailure">Creates a possible failure.</param>
 	/// <returns>A new failed result if the value of <paramref name="predicate" /> is <see langword="true" />; otherwise, the previous result.</returns>
 	public Result<TFailure, TSuccess> Ensure(Func<TSuccess, bool> predicate, Func<TSuccess, TFailure> createFailure)
 		=> Ensure(predicate, createFailure(Success));
 
 	/// <summary>Creates a new failed result if the value of <paramref name="predicate" /> is <see langword="true" />; otherwise, returns the previous result.</summary>
 	/// <param name="predicate">Creates a set of criteria.</param>
-	/// <param name="failure">The possible failure.</param>
+	/// <param name="failure">A possible failure.</param>
 	/// <returns>A new failed result if the value of <paramref name="predicate" /> is <see langword="true" />; otherwise, the previous result.</returns>
 	public Result<TFailure, TSuccess> Ensure(Func<TSuccess, bool> predicate, TFailure failure)
 	{
@@ -114,19 +114,19 @@ public Result(TSuccess success)
 	}
 
 	/// <summary>Creates a new failed result if the value of <paramref name="predicate" /> is <see langword="true" />; otherwise, returns the previous result.</summary>
-	/// <param name="createAuxiliary">Creates the auxiliary to use in combination with <paramref name="predicate" /> and <paramref name="createFailure" />.</param>
+	/// <param name="createAuxiliary">Creates an auxiliary to use in combination with <paramref name="predicate" /> and <paramref name="createFailure" />.</param>
 	/// <param name="predicate">Creates a set of criteria.</param>
-	/// <param name="createFailure">Creates the possible failure.</param>
+	/// <param name="createFailure">Creates a possible failure.</param>
 	/// <typeparam name="TAuxiliary">Type of auxiliary.</typeparam>
 	/// <returns>A new failed result if the value of <paramref name="predicate" /> is <see langword="true" />; otherwise, the previous result.</returns>
 	public Result<TFailure, TSuccess> Ensure<TAuxiliary>(Func<TAuxiliary> createAuxiliary,
 		Func<TSuccess, TAuxiliary, bool> predicate, Func<TSuccess, TAuxiliary, TFailure> createFailure)
 		=> Ensure(createAuxiliary(), predicate, createFailure);
 
 	/// <summary>Creates a new failed result if the value of <paramref name="predicate" /> is <see langword="true" />; otherwise, returns the previous result.</summary>
-	/// <param name="auxiliary">The auxiliary to use in combination with <paramref name="predicate" /> and <paramref name="createFailure" />.</param>
+	/// <param name="auxiliary">An auxiliary to use in combination with <paramref name="predicate" /> and <paramref name="createFailure" />.</param>
 	/// <param name="predicate">Creates a set of criteria.</param>
-	/// <param name="createFailure">Creates the possible failure.</param>
+	/// <param name="createFailure">Creates a possible failure.</param>
 	/// <typeparam name="TAuxiliary">Type of auxiliary.</typeparam>
 	/// <returns>A new failed result if the value of <paramref name="predicate" /> is <see langword="true" />; otherwise, the previous result.</returns>
 	public Result<TFailure, TSuccess> Ensure<TAuxiliary>(TAuxiliary auxiliary,
@@ -168,14 +168,14 @@ public Result(TSuccess success)
 	}
 
 	/// <summary>Creates a new result with the same or different type of expected success.</summary>
-	/// <param name="createSuccessToMap">Creates the expected success to map.</param>
+	/// <param name="createSuccessToMap">Creates an expected success to map.</param>
 	/// <typeparam name="TSuccessToMap">Type of expected success to map.</typeparam>
 	/// <returns>A new result with the same or different type of expected success.</returns>
 	public Result<TFailure, TSuccessToMap> Map<TSuccessToMap>(Func<TSuccess, TSuccessToMap> createSuccessToMap)
 		=> Map(createSuccessToMap(Success));
 
 	/// <summary>Creates a new result with the same or different type of expected success.</summary>
-	/// <param name="successToMap">The expected success to map.</param>
+	/// <param name="successToMap">An expected success to map.</param>
 	/// <typeparam name="TSuccessToMap">Type of expected success to map.</typeparam>
 	/// <returns>A new result with the same or different type of expected success.</returns>
 	public Result<TFailure, TSuccessToMap> Map<TSuccessToMap>(TSuccessToMap successToMap)
@@ -194,8 +194,8 @@ public Result(TSuccess success)
 			: createResultToBind(Success);
 
 	/// <summary>Creates a new reduced failure if the previous result is failed; otherwise, creates a new reduced success.</summary>
-	/// <param name="reduceFailure">Creates the possible reduced failure.</param>
-	/// <param name="reduceSuccess">Creates the expected reduced success.</param>
+	/// <param name="reduceFailure">Creates a possible reduced failure.</param>
+	/// <param name="reduceSuccess">Creates an expected reduced success.</param>
 	/// <typeparam name="TReducer">Type of reducer.</typeparam>
 	/// <returns>A new reduced failure if the previous result is failed; otherwise, a new reduced success.</returns>
 	public TReducer Reduce<TReducer>(Func<TFailure, TReducer> reduceFailure, Func<TSuccess, TReducer> reduceSuccess)