Update the docs for version 3.1.0

Author: TolikPylypchuk

docs/articles/async.md

@@ -1,52 +1,55 @@
 # Asynchronous Pattern Matching
 
-Starting with version 3.0 asynchronous pattern matching is also available.
+Starting with version 3.0, asynchronous pattern matching is also available.
+
+> [!IMPORTANT]
+> On .NET Standard 2.0, Matchmaker uses
+> [Microsoft.Bcl.AsyncInterfaces](https://www.nuget.org/packages/Microsoft.Bcl.AsyncInterfaces) as the polyfill for
+> asynchronous interfaces.
 
 ## Async Patterns
 
 Async patterns are objects which implement the `Matchmaker.Patterns.Async.IAsyncPattern<TInput, TMatchResult>`
-interface. They are very similar to [normal patterns](patterns.md), except they are, well, matched asynchronously.
-The interface contains two members:
+interface. They are very similar to [normal patterns](patterns.md), except they are matched asynchronously. The
+interface contains two members:
 
-```
+```c#
 string Description { get; }
 
 Task<MatchResult<TMatchResult>> MatchAsync(Tinput input);
 ```
 
-The predefined patterns (contained in the `Matchmaker.Patterns.Async.AsyncPattern` class) and extension methods
-from `MatchMaker.Linq` are basically the same. There are also extensions for `Task<MatchResult<TMatchResult>>`.
+The predefined patterns (contained in the `Matchmaker.Patterns.Async.AsyncPattern` class) and extension methods from
+`MatchMaker.Linq` are basically the same. There are also extensions for `Task<MatchResult<TMatchResult>>`.
 
 The only difference is that the `Cached` extension method returns a pattern which caches its inputs in a thread-safe
 manner.
 
 Creating custom async patterns is also basically the same as creating custom patterns: you can use the `CreatePattern`
-methods from the `AsyncPattern` class, extend the
-`Matchmaker.Patterns.Async.AsyncPattern<TInput, TMatchResult>` class to get the `Description` property for
-free, or implement the `IAsyncPattern<TInput, TMatchResult>` directly (which is not recommended).
+methods from the `AsyncPattern` class, extend the `Matchmaker.Patterns.Async.AsyncPattern<TInput, TMatchResult>` class
+to get the `Description` property for free, or implement the `IAsyncPattern<TInput, TMatchResult>` directly.
 
-Normal patterns can be turned into async patterns by calling the `AsAsync()` extension (defined in the
-`Matchmaker.Linq` namespace).
+Normal patterns can be turned into async patterns by calling the `AsAsync()` extension (defined in the `Matchmaker.Linq`
+namespace).
 
 ## Async Match Expressions
 
 Async match expressions are also very similar to [normal match expressions](expressions.md). There are two types of
-async match expressions: `AsyncMatch<TInput, TOutput>` which yields a result and `AsyncMatch<TInput>` which
-doesn't. They can be created using methods in the `AsyncMatch` class.
+async match expressions: `AsyncMatch<TInput, TOutput>` which yields a result and `AsyncMatch<TInput>` which doesn't.
+They can be created using methods in the `AsyncMatch` class.
 
-The `Case` methods of async match expressions are overloaded to take either async patterns or normal patterns (which
-are turned into async patterns using the `AsAsync()` extension) and to take either async or sync actions to executed
-when a pattern is matched successfully (sync actions are turned into pseudo-async actions).
+The `Case` methods of async match expressions are overloaded to take either async patterns or normal patterns (which are
+turned into async patterns using the `AsAsync()` extension) and to take either async or sync actions to executed when a
+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 enable lazy async execution of match expressions.
 
-The `Matchmaker.Linq` namespace contains the `EnumerateAsync` extension method for `IEnumerable<T>` which
+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.
 
-Static async match expressions are also available. Use the `AsyncMatch.CreateStatic` methods to create them, just
-like normal match expressions. The methods accept an action on either `AsyncMatchBuilder<TInput, TOutput>` or
-`AsyncMatchBuilder<TInput>`. Static match expressions are globally cached and the caching process is thread-safe.
-Caches can be cleared with the `ClearCache` methods in `AsyncMatch`.
+Static async match expressions are also available. Use the `AsyncMatch.CreateStatic` methods to create them, just like
+normal match expressions. The methods accept an action on either `AsyncMatchBuilder<TInput, TOutput>` or
+`AsyncMatchBuilder<TInput>`. Static match expressions are globally cached and the caching process is thread-safe. Caches
+can be cleared with the `ClearCache` methods in `AsyncMatch`.

docs/articles/expressions.md

@@ -1,8 +1,8 @@
 # Match Expressions
 
-The second central idea is the match expression itself. It is represented by two classes: `Match<TInput, TOutput>`
-and `Match<TInput>`. The difference between them is that the former represents a match expression which yields
-a result, and the latter represents a match expression which doesn't yield a result (also known as match statement).
+The second central idea is the match expression itself. It is represented by two classes: `Match<TInput, TOutput>` and
+`Match<TInput>`. The difference between them is that the former represents a match expression which yields a result, and
+the latter represents a match expression which doesn't yield a result (also known as a match statement).
 
 ## Using Match Expressions
 
@@ -12,27 +12,27 @@ 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 ones on which they are called.
+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
+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
 
-To execute a match expression, the `ExecuteOn` method is used. It takes the input value to match. There are two modes
-of execution in match expressions: strict and non-strict. The strict mode throws an exception if no matches were found,
-and the non-strict doesn't.
+To execute a match expression, the `ExecuteOn` method is used. It takes the input value to match. There are two modes of
+execution in match expressions: strict and non-strict. The strict mode throws an exception if no matches were found, and
+the non-strict doesn't.
 
-In the `Match<TInput, TOutput>` class the `ExecuteOn` method returns the result of the match or throws a
-`MatchException` if no successful match was found. `Match<TInput, TOutput>` also contains the `ExecuteNonStrict`
-method which executes the match expression in the non-strict mode. It returns `MatchResult<TOutput>` because
-the result might not be present.
+In the `Match<TInput, TOutput>` class, the `ExecuteOn` method returns the result of the match or throws a
+`MatchException` if no successful match was found. `Match<TInput, TOutput>` also contains the `ExecuteNonStrict` method
+which executes the match expression in the non-strict mode. It returns `MatchResult<TOutput>` because the result might
+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 indicates whether the match was successful and doesn't throw an exception if it wasn't.
+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
+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
 the match expression.
@@ -45,7 +45,7 @@ Fall-through must be explicitly enabled for cases and then explicitly enabled du
 contain the `ExecuteWithFallthrough` method which takes fall-through behavior into account. `ExecuteOn` and
 `ExecuteStrict` ignore the fall-through behavior.
 
-If a case has fall-through enabled, then the expression falls to the _next successful_ match, unlike `switch`, which
+If a case has fall-through enabled, then the expression falls to the next successful match, unlike `switch`, which
 falls to the next case whether it's successful or not.
 
 The `Case` methods are overloaded to accept a boolean value which indicates the fall-through behavior. If fall-through
@@ -54,30 +54,30 @@ 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 whether to throw an exception or not if there were no successful matches.
+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 be used to get all successful match results.
+In the `Match<TInput, TOutput>` class, the `ExecuteWithFallthrough` method returns an `IEnumerable<TOutput>` which can
+be used to get all successful match results.
 
-In the `Match<TInput>` class there are no results, so the `ExecuteWithFallthrough` method returns
-an `IEnumerable<object>` which should be used simply to enumerate the match process itself. This is implemented
-so that matching with fall-through is also lazy in this class. The values of the resulting enumerable don't matter -
-in fact, they are always `null`, because match statements don't produce any results. What matters is the process
-of enumeration.
+In the `Match<TInput>` class there are no results, so the `ExecuteWithFallthrough` method returns an
+`IEnumerable<object>` which should be used simply to enumerate the match process itself. This is implemented so that
+matching with fall-through is also lazy in this class. The values of the resulting enumerable don't matter - in fact,
+they are always `null`, because match statements don't produce any results. What matters is the process of enumeration.
 
-You can use the LINQ's `Take` method to limit the number of executed matches, or the `Count` method to execute it
-and get the number of successful matches.
+You can use the LINQ's `Take` method to limit the number of executed matches, or the `Count` method to execute it and
+get the number of successful matches.
 
-The `Matchmaker.Linq` namespace contains the `Enumerate` extension method for `IEnumerable<T>` which enumerates
-it and ignores the result. You can use it if you just want to execute the match statement with fall-through.
+The `Matchmaker.Linq` namespace contains the `Enumerate` extension method for `IEnumerable<T>` which enumerates it and
+ignores the result. You can use it if you just want to execute the match statement with fall-through.
 
-**Remember: matching with fall-through is lazy and is actually executed when the result is enumerated.**
+> [!IMPORTANT]
+> Matching with fall-through is lazy and is actually executed when the result is enumerated.
 
 Here's a (somewhat convoluted) implementation of the famous fizz-buzz program which uses matching with fall-through:
 
-```
+```c#
 using System.Linq;
 
 using Matchmaker;
@@ -99,7 +99,8 @@ var result = Enumerable.Range(0, 15)
     .Select(items => items.Aggregate(String.Concat))
     .ToList();
 
-// The result is ("FizzBuzz", "1", "2", "Fizz", "4", "Buzz", "Fizz", "7", "8", "Fizz", "Buzz", "11", "Fizz", "13", "14", "FizzBuzz");
+// The result is:
+// "FizzBuzz", "1", "2", "Fizz", "4", "Buzz", "Fizz", "7", "8", "Fizz", "Buzz", "11", "Fizz", "13", "14", "FizzBuzz"
 ```
 
 ## Static Match Expressions
@@ -109,7 +110,7 @@ var result = Enumerable.Range(0, 15)
 One pain point of match expressions is that whenever a method which contains a match expression is executed, the match
 expression is initialized from scratch. Take a look at this example:
 
-```
+```c#
 void DoStuff(int i) =>
     Match.Create<int, string>()
         .Case(...)
@@ -119,21 +120,21 @@ void DoStuff(int i) =>
         .ExecuteOn(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, to the lag does
+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.
 
-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.
+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:
+The `Match` class contains the `CreateStatic` methods which allow the creation of static match expressions. Take a look
+at the modified example:
 
-```
+```c#
 void DoStuff(int i) =>
     Match.CreateStatic<int, string>(builder => builder
             .Case(...)
@@ -147,14 +148,14 @@ It looks almost the same, except for one difference: the calls to `Case` methods
 called the build action, which is passed to the `CreateStatic` method. Now this match expression will be initialized
 only once, and its initialization code is in the same place as its execution point.
 
-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.
+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.
 
 `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:
 
-```
+```c#
 builder
     .Fallthrough(true)
     .Case(...) // this case has fall-through behavior if not specified otherwise
@@ -168,14 +169,14 @@ Every case can configure its fall-through behavior individually as well.
 
 ### Caching Match Expressions
 
-The build action will be called only once, and its result will be cached. The cache is a static hash-table.
-The caching process is not thread-safe.
+The build action will be called only once, and its result will be cached. The cache is a static hash-table. The caching
+process is not thread-safe.
 
 The key of the cache is the place where the `CreateStatic` method is called. Apart from the build action, this method
-also accepts two caller info arguments: the path to the source file and the line in the source file. Users don't
-need to pass these arguments to the method as they have the `CallerFilePath` and `CallerLineNumber` attributes.
+also accepts two caller info arguments: the path to the source file and the line in the source file. Users don't need to
+pass these arguments to the method as they have the `CallerFilePath` and `CallerLineNumber` attributes.
 
-The `Match` class also contains the `ClearCache` methods which clear a global cache. Match expressions have a cache
-per type (so `Match<int, int>` uses a different cache than `Match<int, string>`) so `ClearCache` only clears one
-cache. Clearing the cache will force all static match expressions of that type to be reinitialized. This process is
-not thread-safe as well.
+The `Match` class also contains the `ClearCache` methods which clear a global cache. Match expressions have a cache per
+type (so `Match<int, int>` uses a different cache than `Match<int, string>`) so `ClearCache` only clears one cache.
+Clearing the cache will force all static match expressions of that type to be reinitialized. This process is not
+thread-safe as well.