docs: clarify descriptions and error messages

README.md

@@ -2,11 +2,11 @@
 [![NuGet](https://img.shields.io/nuget/v/Ramstack.Parsing.svg)](https://nuget.org/packages/Ramstack.Parsing)
 [![MIT](https://img.shields.io/github/license/rameel/ramstack.parsing)](https://github.com/rameel/ramstack.parsing/blob/main/LICENSE)
 
-A blazing-fast, lightweight, and intuitive parser combinator library for .NET.
+A fast, lightweight parser combinator library for .NET.
 
 ## Getting Started
 
-To install the `Ramstack.Parsing` [NuGet package](https://www.nuget.org/packages/Ramstack.Parsing) to your project, run the following command:
+To add the `Ramstack.Parsing` [NuGet package](https://www.nuget.org/packages/Ramstack.Parsing) to your project, run:
 ```shell
 dotnet add package Ramstack.Parsing
 ```
@@ -59,7 +59,7 @@ private static Parser<double> CreateParser()
 }
 ```
 
-As you can see, the parser is highly readable and easy to define. Using it is just as simple:
+Use the parser as follows:
 
 ```csharp
 var result = Calc.Parse(expression);
@@ -73,8 +73,8 @@ else
     Console.WriteLine(result.ErrorMessage);
 
     //
-    // result.ToString() prints the parsed value or an error message
-    // depending on the parsing status
+    // result.ToString() returns the parsed value as a string,
+    // or an error message if parsing fails.
     //
     // Console.WriteLine(result);
     //

src/Ramstack.Parsing/Character.cs

@@ -13,12 +13,12 @@ public static class Character
     public static Parser<char> Letter => L(GeneralUnicodeCategory.Letter).As("letter");
 
     /// <summary>
-    /// Gets a parser that matches a single upper letter character.
+    /// Gets a parser that matches a single uppercase letter.
     /// </summary>
     public static Parser<char> Uppercase => L(GeneralUnicodeCategory.UppercaseLetter).As("uppercase letter");
 
     /// <summary>
-    /// Gets a parser that matches a single lower letter character.
+    /// Gets a parser that matches a single lowercase letter.
     /// </summary>
     public static Parser<char> Lowercase => L(GeneralUnicodeCategory.LowercaseLetter).As("lowercase letter");
 

src/Ramstack.Parsing/GeneralUnicodeCategory.cs

@@ -36,7 +36,7 @@ public enum GeneralUnicodeCategory
     TitlecaseLetter = 1 << UnicodeCategory.TitlecaseLetter,
 
     /// <summary>
-    /// Modifier letter character, which is free-standing spacing character
+    /// Modifier letter character, which is a free-standing spacing character
     /// that indicates modifications of a preceding letter.
     /// Signified by the Unicode designation "Lm" (letter, modifier).
     /// </summary>
@@ -70,20 +70,20 @@ public enum GeneralUnicodeCategory
     EnclosingMark = 1 << UnicodeCategory.EnclosingMark,
 
     /// <summary>
-    /// Decimal digit character, that is, a character in the range 0 through 9.
+    /// A decimal digit with a value from 0 to 9, including digits from non-Latin scripts.
     /// Signified by the Unicode designation "Nd" (number, decimal digit).
     /// </summary>
     DecimalDigitNumber = 1 << UnicodeCategory.DecimalDigitNumber,
 
     /// <summary>
     /// Number represented by a letter, instead of a decimal digit,
-    /// for example, the Roman numeral for five, which is "V".
+    /// for example, the Roman numeral five, "Ⅴ" (U+2164).
     /// The indicator is signified by the Unicode designation "Nl" (number, letter).
     /// </summary>
     LetterNumber = 1 << UnicodeCategory.LetterNumber,
 
     /// <summary>
-    /// Number that is neither a decimal digit nor a letter number, for example, the fraction 1/2.
+    /// Number that is neither a decimal digit nor a letter number, for example, the fraction "½" (U+00BD).
     /// The indicator is signified by the Unicode designation "No" (number, other).
     /// </summary>
     OtherNumber = 1 << UnicodeCategory.OtherNumber,
@@ -178,7 +178,7 @@ public enum GeneralUnicodeCategory
     OtherPunctuation = 1 << UnicodeCategory.OtherPunctuation,
 
     /// <summary>
-    /// Mathematical symbol character, such as "+" or "= ".
+    /// Mathematical symbol character, such as "+" or "=".
     /// Signified by the Unicode designation "Sm" (symbol, math).
     /// </summary>
     MathSymbol = 1 << UnicodeCategory.MathSymbol,
@@ -190,9 +190,7 @@ public enum GeneralUnicodeCategory
     CurrencySymbol = 1 << UnicodeCategory.CurrencySymbol,
 
     /// <summary>
-    /// Modifier symbol character, which indicates modifications of surrounding characters.
-    /// For example, the fraction slash indicates that the number to the left is the numerator
-    /// and the number to the right is the denominator.
+    /// Modifier symbol character, such as the circumflex accent "^" (U+005E).
     /// The indicator is signified by the Unicode designation "Sk" (symbol, modifier).
     /// </summary>
     ModifierSymbol = 1 << UnicodeCategory.ModifierSymbol,
@@ -204,7 +202,7 @@ public enum GeneralUnicodeCategory
     OtherSymbol = 1 << UnicodeCategory.OtherSymbol,
 
     /// <summary>
-    /// Character that is not assigned to any Unicode category.
+    /// A code point that has not been assigned to a character.
     /// Signified by the Unicode designation "Cn" (other, not assigned).
     /// </summary>
     OtherNotAssigned = 1 << UnicodeCategory.OtherNotAssigned,
@@ -263,7 +261,7 @@ public enum GeneralUnicodeCategory
 
     /// <summary>
     /// Represents any symbol category, including math, currency, modifier, and other symbols.
-    /// Signified by the Unicode designation "S" ("Sm", "Sc", "Sk", "So", ).
+    /// Signified by the Unicode designation "S" ("Sm", "Sc", "Sk", "So").
     /// </summary>
     Symbol =
         MathSymbol
@@ -272,7 +270,7 @@ public enum GeneralUnicodeCategory
         | OtherSymbol,
 
     /// <summary>
-    /// Represents any control category, including control, format, surrogate, private use, and other not assigned characters.
+    /// Includes control, format, surrogate, private-use, and unassigned code points.
     /// Signified by the Unicode designation "C" ("Cc", "Cf", "Cs", "Co", "Cn").
     /// </summary>
     Other =

src/Ramstack.Parsing/Literal.Number.cs

@@ -41,7 +41,7 @@ public static Parser<T> Number<T>(string? name, NumberKind kind = NumberKind.Aut
         {
             return kind is NumberKind.Auto or NumberKind.Float
                 ? new NumberLiteral<T, FloatLiteralKind>(name ?? "floating-point number", NumberStyles.Float)
-                : throw new ArgumentException($"The number kind {kind} are not supported on floating-point types.", nameof(kind));
+                : throw new ArgumentException($"Number kind {kind} is not supported for floating-point types.", nameof(kind));
         }
 
         if (typeof(T) == typeof(sbyte)
@@ -72,11 +72,11 @@ public static Parser<T> Number<T>(string? name, NumberKind kind = NumberKind.Aut
             #endif
 
             throw new ArgumentException(
-                $"The number kind {kind} are not supported on integer numeric types.",
+                $"Number kind {kind} is not supported for integer types.",
                 nameof(kind));
         }
 
-        throw new InvalidOperationException($"The specified type {typeof(T)} are not supported.");
+        throw new InvalidOperationException($"Type {typeof(T)} is not supported.");
     }
 
     private static int TryParseNumber<TKind>(ref char span, int length, int p)

src/Ramstack.Parsing/Literal.cs

@@ -1,6 +1,6 @@
 namespace Ramstack.Parsing;
 
 /// <summary>
-/// Provides parsers for parsing literal values such as booleans, numbers, strings, and characters.
+/// Provides parsers for numbers, strings, characters, and escape sequences.
 /// </summary>
 public static partial class Literal;

src/Ramstack.Parsing/NumberKind.cs

@@ -6,7 +6,7 @@ namespace Ramstack.Parsing;
 public enum NumberKind
 {
     /// <summary>
-    /// Automatically determines the numeric type that can be parsed.
+    /// Selects the numeric format based on the target type.
     /// </summary>
     Auto,
 

src/Ramstack.Parsing/ParseContext.cs

@@ -217,7 +217,7 @@ public DiagnosticState SuppressDiagnostics()
     /// "Expected digit" or "Expected '.'". However, all these messages are eventually
     /// discarded in favor of a single top-level error from the <c>float</c> parser.<br/><br/>
     ///
-    /// By suppressing sub-parsers diagnostics and only producing a concise top-level message
+    /// By suppressing diagnostics from sub-parsers and only producing a concise top-level message
     /// like "(1:5) Expected float" we avoid unnecessary memory allocations and generally
     /// do less work, which ultimately improves performance.
     /// </para>
@@ -226,7 +226,7 @@ public DiagnosticState SuppressDiagnostics()
     /// <code>
     /// var previousState = context.SuppressDiagnosticsIfNamed(Name);
     /// // ... parsing logic ...
-    /// context.RestoreDiagnostics(previousState);
+    /// context.RestoreDiagnosticState(previousState);
     /// </code>
     /// </example>
     public DiagnosticState SuppressDiagnosticsIfNamed(string? name)

src/Ramstack.Parsing/Parser.Between.cs

@@ -22,8 +22,8 @@ public static Parser<T> Between<T, TAround>(this Parser<T> parser, Parser<TAroun
     /// returning the result of the main parser.
     /// </summary>
     /// <typeparam name="T">The type of the value produced by the main parser.</typeparam>
-    /// <typeparam name="TBefore">The type of the parser applied before the main parser (ignored in the final result).</typeparam>
-    /// <typeparam name="TAfter">The type of the parser applied after the main parser (ignored in the final result).</typeparam>
+    /// <typeparam name="TBefore">The type of value produced by the parser applied before the main parser (ignored in the final result).</typeparam>
+    /// <typeparam name="TAfter">The type of value produced by the parser applied after the main parser (ignored in the final result).</typeparam>
     /// <param name="parser">The main parser whose result will be returned.</param>
     /// <param name="before">The parser to apply before the main parser.</param>
     /// <param name="after">The parser to apply after the main parser.</param>

src/Ramstack.Parsing/Parser.DefaultOnFail.cs

@@ -4,14 +4,14 @@ partial class Parser
 {
     /// <summary>
     /// Creates an optional parser that always succeeds, returning the parsed value if successful,
-    /// or a default value of the <typeparamref name="T"/> if the specified parser fails.
+    /// or the default value of <typeparamref name="T"/> if the specified parser fails.
     /// </summary>
     /// <typeparam name="T">The type of value produced by the initial parser.</typeparam>
     /// <param name="parser">The parser to be treated as optional.
-    /// If this parser fails to parse, the method will return the default value of the type.</param>
+    /// If parsing fails, the resulting parser returns the default value of <typeparamref name="T"/>.</param>
     /// <returns>
     /// A parser that always succeeds, either by producing a value from the original parser
-    /// or by returning the default value of the <typeparamref name="T"/>.
+    /// or by returning the default value of <typeparamref name="T"/>.
     /// </returns>
     public static Parser<T?> DefaultOnFail<T>(this Parser<T> parser) =>
         parser.DefaultOnFail(default!)!;
@@ -22,7 +22,7 @@ partial class Parser
     /// </summary>
     /// <typeparam name="T">The type of value produced by the initial parser.</typeparam>
     /// <param name="parser">The parser to be treated as optional.
-    /// If this parser fails to parse, the method will return the default value of the type.</param>
+    /// If parsing fails, the resulting parser returns <paramref name="defaultValue"/>.</param>
     /// <param name="defaultValue">The default value to return if the specified parser fails to parse.</param>
     /// <returns>
     /// A parser that always succeeds, either by producing a value from the initial parser
@@ -44,7 +44,7 @@ public static Parser<T> DefaultOnFail<T>(this Parser<T> parser, T defaultValue)
     /// </summary>
     /// <typeparam name="T">The type of value produced by the initial parser.</typeparam>
     /// <param name="parser">The parser to be treated as optional.
-    /// If this parser fails to parse, the method will return the default value of the type.</param>
+    /// If parsing fails, the resulting parser returns <paramref name="defaultValue"/>.</param>
     /// <param name="defaultValue">The default value to return if the initial parser fails to parse.</param>
     private sealed class DefaultOnFailParser<T>(Parser<T> parser, T defaultValue) : Parser<T>
     {

src/Ramstack.Parsing/Parser.Do.Generated.cs

@@ -118,7 +118,7 @@ public static Parser<TResult> Do<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, TResul
     /// Represents a parser that applies a transformation function to the value produced by the specified parser.
     /// </summary>
     /// <param name="parser">The parser whose output will be transformed.</param>
-    /// <param name="func">The function  used to transform the parser's output.</param>
+    /// <param name="func">The function used to transform the parser's output.</param>
     private sealed class DoParser<T1, T2, TResult>(Parser<(T1, T2)> parser, Func<T1, T2, TResult> func) : Parser<TResult>
     {
         /// <inheritdoc />
@@ -151,7 +151,7 @@ protected internal override Parser<Unit> ToVoidParser() =>
     /// Represents a parser that applies a transformation function to the value produced by the specified parser.
     /// </summary>
     /// <param name="parser">The parser whose output will be transformed.</param>
-    /// <param name="func">The function  used to transform the parser's output.</param>
+    /// <param name="func">The function used to transform the parser's output.</param>
     private sealed class DoParser<T1, T2, T3, TResult>(Parser<(T1, T2, T3)> parser, Func<T1, T2, T3, TResult> func) : Parser<TResult>
     {
         /// <inheritdoc />
@@ -184,7 +184,7 @@ protected internal override Parser<Unit> ToVoidParser() =>
     /// Represents a parser that applies a transformation function to the value produced by the specified parser.
     /// </summary>
     /// <param name="parser">The parser whose output will be transformed.</param>
-    /// <param name="func">The function  used to transform the parser's output.</param>
+    /// <param name="func">The function used to transform the parser's output.</param>
     private sealed class DoParser<T1, T2, T3, T4, TResult>(Parser<(T1, T2, T3, T4)> parser, Func<T1, T2, T3, T4, TResult> func) : Parser<TResult>
     {
         /// <inheritdoc />
@@ -217,7 +217,7 @@ protected internal override Parser<Unit> ToVoidParser() =>
     /// Represents a parser that applies a transformation function to the value produced by the specified parser.
     /// </summary>
     /// <param name="parser">The parser whose output will be transformed.</param>
-    /// <param name="func">The function  used to transform the parser's output.</param>
+    /// <param name="func">The function used to transform the parser's output.</param>
     private sealed class DoParser<T1, T2, T3, T4, T5, TResult>(Parser<(T1, T2, T3, T4, T5)> parser, Func<T1, T2, T3, T4, T5, TResult> func) : Parser<TResult>
     {
         /// <inheritdoc />
@@ -250,7 +250,7 @@ protected internal override Parser<Unit> ToVoidParser() =>
     /// Represents a parser that applies a transformation function to the value produced by the specified parser.
     /// </summary>
     /// <param name="parser">The parser whose output will be transformed.</param>
-    /// <param name="func">The function  used to transform the parser's output.</param>
+    /// <param name="func">The function used to transform the parser's output.</param>
     private sealed class DoParser<T1, T2, T3, T4, T5, T6, TResult>(Parser<(T1, T2, T3, T4, T5, T6)> parser, Func<T1, T2, T3, T4, T5, T6, TResult> func) : Parser<TResult>
     {
         /// <inheritdoc />
@@ -283,7 +283,7 @@ protected internal override Parser<Unit> ToVoidParser() =>
     /// Represents a parser that applies a transformation function to the value produced by the specified parser.
     /// </summary>
     /// <param name="parser">The parser whose output will be transformed.</param>
-    /// <param name="func">The function  used to transform the parser's output.</param>
+    /// <param name="func">The function used to transform the parser's output.</param>
     private sealed class DoParser<T1, T2, T3, T4, T5, T6, T7, TResult>(Parser<(T1, T2, T3, T4, T5, T6, T7)> parser, Func<T1, T2, T3, T4, T5, T6, T7, TResult> func) : Parser<TResult>
     {
         /// <inheritdoc />
@@ -316,7 +316,7 @@ protected internal override Parser<Unit> ToVoidParser() =>
     /// Represents a parser that applies a transformation function to the value produced by the specified parser.
     /// </summary>
     /// <param name="parser">The parser whose output will be transformed.</param>
-    /// <param name="func">The function  used to transform the parser's output.</param>
+    /// <param name="func">The function used to transform the parser's output.</param>
     private sealed class DoParser<T1, T2, T3, T4, T5, T6, T7, T8, TResult>(Parser<(T1, T2, T3, T4, T5, T6, T7, T8)> parser, Func<T1, T2, T3, T4, T5, T6, T7, T8, TResult> func) : Parser<TResult>
     {
         /// <inheritdoc />
@@ -349,7 +349,7 @@ protected internal override Parser<Unit> ToVoidParser() =>
     /// Represents a parser that applies a transformation function to the value produced by the specified parser.
     /// </summary>
     /// <param name="parser">The parser whose output will be transformed.</param>
-    /// <param name="func">The function  used to transform the parser's output.</param>
+    /// <param name="func">The function used to transform the parser's output.</param>
     private sealed class DoParser<T1, T2, T3, T4, T5, T6, T7, T8, T9, TResult>(Parser<(T1, T2, T3, T4, T5, T6, T7, T8, T9)> parser, Func<T1, T2, T3, T4, T5, T6, T7, T8, T9, TResult> func) : Parser<TResult>
     {
         /// <inheritdoc />
@@ -382,7 +382,7 @@ protected internal override Parser<Unit> ToVoidParser() =>
     /// Represents a parser that applies a transformation function to the value produced by the specified parser.
     /// </summary>
     /// <param name="parser">The parser whose output will be transformed.</param>
-    /// <param name="func">The function  used to transform the parser's output.</param>
+    /// <param name="func">The function used to transform the parser's output.</param>
     private sealed class DoParser<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, TResult>(Parser<(T1, T2, T3, T4, T5, T6, T7, T8, T9, T10)> parser, Func<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, TResult> func) : Parser<TResult>
     {
         /// <inheritdoc />

src/Ramstack.Parsing/Parser.Do.tt

@@ -39,7 +39,7 @@ partial class Parser
     /// Represents a parser that applies a transformation function to the value produced by the specified parser.
     /// </summary>
     /// <param name="parser">The parser whose output will be transformed.</param>
-    /// <param name="func">The function  used to transform the parser's output.</param>
+    /// <param name="func">The function used to transform the parser's output.</param>
     private sealed class DoParser<<#=GenerateGenericParameters(arity)#>, TResult>(Parser<(<#=GenerateGenericParameters(arity)#>)> parser, Func<<#=GenerateGenericParameters(arity)#>, TResult> func) : Parser<TResult>
     {
         /// <inheritdoc />

src/Ramstack.Parsing/Parser.Eol.cs

@@ -3,14 +3,14 @@ namespace Ramstack.Parsing;
 partial class Parser
 {
     /// <summary>
-    /// Gets a parser that matches the end of line.
+    /// Gets a parser that matches and consumes a line break, or succeeds at the end of input.
     /// </summary>
     public static Parser<Unit> Eol { get; } = new EolParser();
 
     #region Inner type: EolParser
 
     /// <summary>
-    /// Represents a parser that matches the end of line.
+    /// Represents a parser that matches and consumes a line break, or succeeds at the end of input.
     /// </summary>
     private sealed class EolParser() : Parser<Unit>("end of line")
     {