Clean up the docs

Author: TolikPylypchuk

CHANGELOG.md

@@ -4,10 +4,10 @@
 
 Whats's new in version 3.1.0:
 
-- .NET Standard 2.0 support was added back, but without nullable reference types
-- Matchmaker is now built with .NET 9
-- Trimming is now enabled only for .NET 6+
+- .NET Standard 2.0 support was added back
 - `BinarryFormatter` support was removed from `MatchException`
+- Matchmaker is now built with .NET 9
+- Trimming is now enabled only for .NET 6 or later
 - Docs now use a new theme
 - Docs for older versions were removed
 
@@ -17,7 +17,7 @@ Whats's new in version 3.0.1:
 
 - No changes to the library's code or API
 - Matchmaker is now built with .NET 6 and uses C# 10 (but still targets .NET Standard 2.1)
-- Improved the NuGet package (added a symbol package, a readme, and Source Link)
+- The NuGet package was improved (a symbol package, a readme, and Source Link were added)
 - The library is now trimmable
 - GitHub Actions are now used for CI instead of AppVeyor
 

Matchmaker/README.md

@@ -62,11 +62,11 @@ an object, and use it multiple times on different input values.
 
 - The default case is a pattern, just like any other. It's called `Any` and is always matched successfully.
 
-- Like in `switch` the patterns are tried out sequentially. This means that the `Any` pattern should always come last.
+- Like in `switch`, the patterns are tried out sequentially. This means that the `Any` pattern should always come last.
 
 C# 8 included a new way to write `switch` expressions which yield a value, and further versions extended it quite a bit.
 This drastically reduced the need for external libraries like this one for pattern matching. However, this library lets
-the user define arbitrary patterns, which makes this library more powerful than the `switch` expressions.
+the user define arbitrary patterns which makes this library more powerful than the `switch` expressions.
 
 Here's what the equivalent switch expression looks like in C# 8 or later:
 
@@ -232,8 +232,8 @@ articles provide everything you need to know to use this library.
 If you need extensive information, go to the [API reference](https://matchmaker.tolik.io/api/index.html).
 
 If you need even more info about this library, you can go through the
-[tests](https://github.com/TolikPylypchuk/Matchmaker/Matchmaker.Tests). They are property-based and as such, they
-describe every aspect of the classes and their members.
+[tests](https://github.com/TolikPylypchuk/Matchmaker/tree/main/Matchmaker.Tests). They are property-based and as such,
+they describe every aspect of the classes and their members.
 
 ## Is This Library Still Maintained?
 

README.md

@@ -70,11 +70,11 @@ an object, and use it multiple times on different input values.
 
 - The default case is a pattern, just like any other. It's called `Any` and is always matched successfully.
 
-- Like in `switch` the patterns are tried out sequentially. This means that the `Any` pattern should always come last.
+- Like in `switch`, the patterns are tried out sequentially. This means that the `Any` pattern should always come last.
 
 C# 8 included a new way to write `switch` expressions which yield a value, and further versions extended it quite a bit.
 This drastically reduced the need for external libraries like this one for pattern matching. However, this library lets
-the user define arbitrary patterns, which makes this library more powerful than the `switch` expressions.
+the user define arbitrary patterns which makes this library more powerful than the `switch` expressions.
 
 Here's what the equivalent switch expression looks like in C# 8 or later:
 
@@ -240,8 +240,8 @@ articles provide everything you need to know to use this library.
 If you need extensive information, go to the [API reference](https://matchmaker.tolik.io/api/index.html).
 
 If you need even more info about this library, you can go through the
-[tests](https://github.com/TolikPylypchuk/Matchmaker/Matchmaker.Tests). They are property-based and as such, they
-describe every aspect of the classes and their members.
+[tests](https://github.com/TolikPylypchuk/Matchmaker/tree/main/Matchmaker.Tests). They are property-based and as such,
+they describe every aspect of the classes and their members.
 
 ## Is This Library Still Maintained?
 

docs/articles/async.md

@@ -44,7 +44,7 @@ pattern is matched successfully (sync actions are turned into async actions).
 
 Async match expressions can be executed using the `ExecuteAsync`, `ExecuteNonStrictAsync` and
 `ExecuteWithFallthroughAsync` methods.  The `ToFunction` method and its variations are also available.
-`ExecuteWithFallthroughAsync` returns an `IAsyncEnumerable` which enable lazy async execution of match expressions.
+`ExecuteWithFallthroughAsync` returns an `IAsyncEnumerable` which enables lazy async execution of match expressions.
 
 The `Matchmaker.Linq` namespace contains the `EnumerateAsync` extension method for `IAsyncEnumerable<T>` which
 enumerates it and ignores the result. You can use it if you just want to execute the match statement with fall-through.

docs/articles/expressions.md

@@ -13,10 +13,10 @@ A match expression can be created using the `Create` methods of the static class
 ### Adding Cases
 
 The `Match` classes include `Case` methods which are used to add a pattern and a function which is executed if the match
-is successful. Match expressions are immutable – `Case` methods return new match expressions; they do not affect the
+is successful. Match expressions are immutable — `Case` methods return new match expressions; they do not affect the
 ones on which they are called.
 
-`Case` methods are generic – they also contain information about the pattern's transformation type. Match expressions
+`Case` methods are generic — they also contain information about the pattern's transformation type. Match expressions
 can contain patterns of arbitrary transformation types without knowing about these types.
 
 ### Executing Match Expressions
@@ -31,7 +31,7 @@ which executes the match expression in the non-strict mode. It returns `MatchRes
 not be present.
 
 In the `Match<TInput>` class, the `ExecuteOn` method doesn't return anything, and also throws a `MatchException` if the
-match wasn't successful. This class also contains the `ExecuteNonStrict` method – it returns a boolean value which
+match wasn't successful. This class also contains the `ExecuteNonStrict` method — it returns a boolean value which
 indicates whether the match was successful and doesn't throw an exception if it wasn't.
 
 The `ToFunction` method and its variations are also available. They return a function which, when called, will execute
@@ -54,8 +54,8 @@ the expression will stop at this pattern and not go any further.
 
 `Match.Create` is also overloaded to take the default fall-through behavior.
 
-Matching with fall-through is lazy i.e. it returns an `IEnumerable` and is only executed when this enumerable is
-enumerated. Because matching will fall-through is lazy, it doesn't have any modes of execution – the user must decide
+Matching with fall-through is lazy, i.e., it returns an `IEnumerable` and is only executed when this enumerable is
+enumerated. Because matching will fall-through is lazy, it doesn't have any modes of execution — the user must decide
 whether to throw an exception or not if there were no successful matches.
 
 In the `Match<TInput, TOutput>` class, the `ExecuteWithFallthrough` method returns an `IEnumerable<TOutput>` which can
@@ -121,15 +121,15 @@ void DoStuff(int i) =>
 ```
 
 The problem here is that if we call `DoStuff` 10,000 times, we will initialize the match expression 10,000 times as
-well, even though it's actually the same expression. Having just 4 cases may not seem like much, but the lag does
-accumulate if we execute it thousands of times.
+well, even though it's actually the same expression. Having just 4 cases may not seem like much, but the lag and
+allocations do accumulate if we execute it thousands of times.
 
 We can save the expression in a field and then call the `ExecuteOn` method on this field. But this makes the code much
 less readable because the case definitions are in a different place from the actual execution point.
 
 ### The Solution
 
-There is a way to create static match expressions – expressions which will be initialized only once.
+There is a way to create static match expressions — expressions which will be initialized only once.
 
 The `Match` class contains the `CreateStatic` methods which allow the creation of static match expressions. Take a look
 at the modified example:
@@ -150,7 +150,7 @@ only once, and its initialization code is in the same place as its execution poi
 
 The parameter of the build action has the type `MatchBuilder<TInput, TOutput` or `MatchBuilder<TInput>`, depending on
 which type of match expressions you are building. This type has the same methods for adding cases as the `Match` classes
-and is mutable – the methods return the same builder instance.
+and is mutable — the methods return the same builder instance.
 
 `MatchBuilder` also has the `Fallthrough` method which specifies the default fall-through behavior. But this method
 specifies fall-through behavior only for cases that are defined after it. For example:

docs/articles/migration.md

@@ -6,12 +6,12 @@ This article describes how to migrate to version 2.0.0 from
 If you need to migrate from older versions, first migrate to version 1.2.0. You can do that just by reading the
 changelog, because previous versions contained much fewer changes and it's much simpler to migrate.
 
-In order to migrate from version 2.0.0 to version 2.1.0 action is required only if you implemented the
+In order to migrate from version 2.0.0 to version 2.1.0, action is required only if you implemented the
 `IPattern<TInput, TMatchResult>` interface (which wasn't recommended). The less generic `IPattern<TInput>` interface was
 removed, so you should remove its `Match` method. That's it.
 
 No changes are required to migrate from version 2.1.0 to 3.1.0. Version 3.0.0 removed support for .NET Standard 2.0, but
-version 3.1.0 added it back, effectively undoing the only breaking change of 3.0.0.
+version 3.1.0 added it back, effectively undoing its only breaking change.
 
 ## General
 

docs/articles/patterns.md

@@ -19,11 +19,11 @@ The `Match` method actually does two things:
 - Matches the input value with the pattern and returns a successful result if the match is successful.
 - Transforms the input value. The returned result contains the transformed value if it's successful.
 
-Since options are not supported natively in C#, a custom type – [`MatchResult<T>`](results.md) – is used.
+Since options are not supported natively in C#, a custom type — [`MatchResult<T>`](results.md) — is used.
 
 The definition of patterns is similar to F#'s active patterns.
 
-Descriptions for patterns are not terribly important, but can be useful for debugging. As such, they are optional – if
+Descriptions for patterns are not terribly important, but can be useful for debugging. As such, they are optional — if
 you don't want a pattern to have a description, it should be empty. A pattern's description should never be `null`.
 
 ## Null Values
@@ -59,7 +59,7 @@ All methods for getting predefined patterns are overloaded to take a custom desc
 The `Matchmaker.Linq` namespace provides several extension methods for patterns:
 
 - `Select` maps a pattern's result value if it's successful.
-- `Pipe` creates a pattern pipeline – the result of the first pattern is the input of the second pattern.
+- `Pipe` creates a pattern pipeline — the result of the first pattern is the input of the second pattern.
 - `Cast` casts a pattern's result to a specified type. It's the same as piping a pattern to the `Type` pattern. If the
 input is `null`, then the match will fail only if the destination type is a non-nullable value type.
 - `Bind` flat-maps a pattern's result. If a pattern's result is successful, it calls the specified function and passes
@@ -70,7 +70,7 @@ result is the final result.
 the input if successful.
 - `Compose` is the same as the three methods above, but the composition operator is passed to it as well.
 - `Cached` returns a pattern which matches the same as the specified pattern but caches its results in a `null`-safe
-hash table. Every input will be matched only once – if it's matched again, the result will be taken from the cache. The
+hash table. Every input will be matched only once — if it's matched again, the result will be taken from the cache. The
 caching process is not thread-safe.
 
 All extension methods for patterns are overloaded to take a custom description.
@@ -82,10 +82,10 @@ a combination of the Reader and Maybe monads.
 
 ## Immutability
 
-Every predefined pattern as well as patterns returned by the `CreatePattern` and extension methods are immutable.
-Calling an extension method on a pattern returns a new pattern – the old one is unchanged.
+All predefined patterns, as well as patterns returned by `CreatePattern` and extension methods, are immutable. Calling
+an extension method on a pattern returns a new pattern — the old one is unchanged.
 
-An exception is the pattern returned by the `Cached` method, which is not immutable – it holds a mutable cache. But if a
+An exception is the pattern returned by the `Cached` method, which is not immutable — it holds a mutable cache. But if a
 pattern is referentially transparent (its `Match` method always returns the same result for the same input and doesn't
 have any side effects), then the caching pattern based on it can be thought of as immutable as well, because it doesn't
 matter how many times the base pattern's `Match` method is called.
@@ -109,7 +109,7 @@ There are also overloads which take a description.
 
 If you want something more complex than a single function, you can create a class which extends the
 `Matchmaker.Patterns.Pattern<TInput, TMatchResult>` class. This is a base class for patterns, and it implements the
-`Description` property which you don't have to use if you don't want – by default the description is empty, which means
+`Description` property which you don't have to use if you don't want — by default the description is empty, which means
 that the pattern doesn't have a description.
 
 You can also implement the `IPattern<TInput, TMatchResult>` interface directly. There is no reason to do that instead of

docs/articles/results.md

@@ -12,8 +12,8 @@ may want just pattern matching and nothing else.
 - Users may use a different library/framework for functional features. There are a lot of those for C#.
 
 So, starting with version 2, instead of using the `OptionUnsafe<T>` type from language-ext, this library includes a
-`MatchResult<T>` type. This type is much like optional types from other libraries in that it may contain a value, or may
-not, except for a couple differences:
+`MatchResult<T>` type. This type works much like optional types from other libraries in that it may contain a value, or
+may not, except for a couple differences:
 
 - `MatchResult<T>` is not a general-purpose optional type and shouldn't be used as such.
 - `MatchResult<T>` can contain `null` values and this is important to remember. This type is not used to avoid

docs/articles/unions.md

@@ -73,7 +73,7 @@ public int Sum(ConsList list)
 
 As you can see, we have to throw an exception in the `switch` version, because C# can't know that `ConsCell` and `Empty`
 are the only possible subclasses of `ConsList`. And for that reason, if we forget to define one of the cases in `switch`
-or in a match, we'll get an exception. In F# a warning is issued when the match is incomplete, but C# doesn't have the
+or in a match, we'll get an exception. In F#, a warning is issued when the match is incomplete, but C# doesn't have the
 notion of complete or incomplete matches. Of course, this match will fail if the provided list is `null`, but this can
 be handled using the `Null` pattern.