expand docs (#20)

.gitignore

@@ -3,4 +3,7 @@
 .devcontainer/
 .swift-version
 
+/swift-biome/
+/*.ss
+
 Package.catalog 

Sources/Grammar/Diagnostics/ParsingDiagnostics.spf

@@ -1,3 +1,5 @@
+/// An abstract interface used by ``ParsingInput`` to emit (or not emit) debugging 
+/// information to.
 @retro public
 protocol ParsingDiagnostics<Source> 
 {

Sources/Grammar/Diagnostics/ParsingDiagnostics.spf.swift

@@ -1,5 +1,7 @@
 
 #if swift(>=5.7)
+/// An abstract interface used by ``ParsingInput`` to emit (or not emit) debugging 
+/// information to.
 public
 protocol ParsingDiagnostics<Source> 
 {
@@ -17,6 +19,8 @@ protocol ParsingDiagnostics<Source>
     func reset(index:inout Source.Index, to:Breadcrumb, because:inout Error) 
 }
 #else 
+/// An abstract interface used by ``ParsingInput`` to emit (or not emit) debugging 
+/// information to.
 public
 protocol ParsingDiagnostics
 {

Sources/Grammar/Digit/DigitRule.spf

@@ -1,3 +1,5 @@
+/// A parsing rule that is applied to a single terminal at a time, and produces 
+/// some ``BinaryInteger`` as its output.
 @retro public
 protocol DigitRule<Terminal, Construction>:TerminalRule where Construction:BinaryInteger
 {    

Sources/Grammar/Digit/DigitRule.spf.swift

@@ -1,5 +1,7 @@
 
 #if swift(>=5.7)
+/// A parsing rule that is applied to a single terminal at a time, and produces 
+/// some ``BinaryInteger`` as its output.
 public
 protocol DigitRule<Terminal, Construction>:TerminalRule where Construction:BinaryInteger
 {    
@@ -10,6 +12,8 @@ protocol DigitRule<Terminal, Construction>:TerminalRule where Construction:Binar
     }
 }
 #else 
+/// A parsing rule that is applied to a single terminal at a time, and produces 
+/// some ``BinaryInteger`` as its output.
 public
 protocol DigitRule:TerminalRule where Construction:BinaryInteger
 {    

Sources/Grammar/Digit/UnicodeDigit.swift

@@ -5,6 +5,8 @@ enum UnicodeDigit<Location, Terminal, Construction> where Construction:BinaryInt
 }
 extension UnicodeDigit where Terminal:BinaryInteger 
 {
+    /// Matches a natural digit, `'1'` through `'9'` ([`0x31 ... 0x39`]()),
+    /// and returns its numeric value.
     public 
     enum Natural:TerminalRule where Construction:BinaryInteger
     {
@@ -19,6 +21,8 @@ extension UnicodeDigit where Terminal:BinaryInteger
             return .init(terminal - 0x30)
         }
     }
+    /// Matches a decimal digit, `'0'` through `'9'` ([`0x30 ... 0x39`]()),
+    /// and returns its numeric value.
     public 
     enum Decimal:DigitRule where Construction:BinaryInteger
     {
@@ -38,6 +42,8 @@ extension UnicodeDigit where Terminal:BinaryInteger
             return .init(terminal - 0x30)
         }
     }
+    /// Matches a hexadecimal digit, without case-sensitivity, 
+    /// and returns its numeric value.
     public 
     enum Hex:DigitRule where Construction:BinaryInteger 
     {
@@ -58,6 +64,7 @@ extension UnicodeDigit where Terminal:BinaryInteger
             }
         }
 
+        /// Matches a lowercase hexadecimal digit, and returns its numeric value.
         public 
         enum Lowercase:DigitRule
         {
@@ -81,6 +88,7 @@ extension UnicodeDigit where Terminal:BinaryInteger
 }
 extension UnicodeDigit where Terminal == Unicode.Scalar 
 {
+    /// Matches a natural digit, [`"1" ... "9"`](), and returns its numeric value.
     public 
     enum NaturalScalar:TerminalRule 
     {
@@ -94,6 +102,7 @@ extension UnicodeDigit where Terminal == Unicode.Scalar
                 Construction.init(terminal.value - ("0" as Unicode.Scalar).value) : nil
         }
     }
+    /// Matches a decimal digit, [`"0" ... "9"`](), and returns its numeric value.
     public 
     enum DecimalScalar:DigitRule 
     {
@@ -112,6 +121,7 @@ extension UnicodeDigit where Terminal == Unicode.Scalar
                 Construction.init(terminal.value - ("0" as Unicode.Scalar).value) : nil
         }
     }
+    /// Matches a hexdecimal digit, without case-sensitivity, and returns its numeric value.
     public 
     enum HexScalar:DigitRule 
     {
@@ -139,6 +149,7 @@ extension UnicodeDigit where Terminal == Unicode.Scalar
             }
         }
 
+        /// Matches a lowercase hexdecimal digit and returns its numeric value.
         public 
         enum Lowercase:DigitRule
         {

Sources/Grammar/Parsing/ASCIITerminal.swift

@@ -1,23 +1,35 @@
-/// A terminal type that can be matched against an ASCII scalar.
+/// A terminal type that can match an ASCII pattern.
+/// 
+/// For example, both a UTF-16 ``Unicode/UTF16//CodeUnit`` and a UTF-8 
+/// ``Unicode/UTF8//CodeUnit`` can be matched against the terminal 
+/// ``UnicodeEncoding//A``.
 public 
 protocol ASCIITerminal:Equatable
 {
     init(_:UInt8)
 }
+/// A terminal type that can match a UTF-8 code unit pattern.
+/// 
+/// For example, a ``Unicode//UTF8/CodeUnit`` can match the UTF-8 
+/// continuation byte [`0x80`](), but it would not make sense to 
+/// match it against a ``Unicode//UTF16/CodeUnit``.
 public 
 protocol UTF8Terminal:ASCIITerminal
 {
 }
+/// A terminal type that can match a UTF-16 code unit pattern.
 public 
 protocol UTF16Terminal:ASCIITerminal
 {
     init(_:UInt16)
 }
+/// A terminal type that can match a ``Unicode/Scalar`` pattern.
 public 
 protocol UnicodeTerminal:ASCIITerminal
 {
     init(_:Unicode.Scalar)
 }
+/// A terminal type that can match a ``Character`` pattern.
 public 
 protocol CharacterTerminal:UnicodeTerminal
 {
@@ -30,9 +42,6 @@ extension UInt8:UTF8Terminal
 extension UInt16:UTF16Terminal 
 {
 }
-/* extension UInt32:UnicodeTerminal 
-{
-} */
 extension Unicode.Scalar:UnicodeTerminal 
 {
 }

Sources/Grammar/Parsing/Grammar.swift

@@ -57,10 +57,10 @@ enum Grammar
     public
     typealias Expected<T> = Pattern.ApplicationError<T> 
         where T:ParsingRule
-    @available(*, deprecated, renamed: "Pattern.AmbiguityError")
+    @available(*, deprecated, renamed: "Pattern.ApplicationError")
     public
-    typealias ExpectedRegion<Base, Exclusion> = Pattern.AmbiguityError<Base, Exclusion> 
-        where Base:ParsingRule, Exclusion:ParsingRule
+    typealias ExpectedRegion<Base, Exclusion> = Pattern.ApplicationError<Base> 
+        where Base:ParsingRule
 
     @available(*, deprecated, renamed: "ParsingRule.parse(diagnosing:)")
     @inlinable public static 
@@ -97,9 +97,14 @@ enum Grammar
     public 
     typealias TerminalClass     = TerminalRule
 
+    /// ``Grammar//NoDiagnostics`` was moved to the top-level 
+    /// namespace of this module.
     @available(*, deprecated, renamed: "NoDiagnostics")
     public 
     typealias NoDiagnostics = _NoDiagnostics 
+
+    /// ``Grammar//DefaultDiagnostics`` was moved to the top-level 
+    /// namespace of this module.
     @available(*, deprecated, renamed: "DefaultDiagnostics")
     public 
     typealias DefaultDiagnostics = _DefaultDiagnostics

Sources/Grammar/Parsing/ParsingError.swift

@@ -2,7 +2,7 @@
 /// stack trace detailing how the parser got there.
 /// 
 /// None of the structured parsers defined in ``/swift-grammar`` throw this error 
-/// directly. Instead, the ``Grammar/DefaultDiagnostics`` engine computes it
+/// directly. Instead, the ``DefaultDiagnostics`` engine computes it
 /// based on the diagnostic engine’s internal state when encountering 
 /// invalid input.
 /// 
@@ -12,7 +12,7 @@ struct ParsingError<Index>:TraceableError, CustomStringConvertible
 {
     /// A diagnostic stack frame, corresponding to a structured ``ParsingRule`` invocation.
     /// 
-    /// Only the ``Grammar/DefaultDiagnostics`` engine tracks call stack state.
+    /// Only the ``DefaultDiagnostics`` engine tracks call stack state.
     @frozen public 
     struct Frame 
     {

Sources/Grammar/Parsing/TraceableError.swift

@@ -1,3 +1,4 @@
+/// A link in a propogated error.
 public 
 protocol TraceableError:Error, CustomStringConvertible 
 {
@@ -15,6 +16,7 @@ protocol TraceableError:Error, CustomStringConvertible
         get 
     }
 }
+/// The root of a propogated error.
 public 
 protocol TraceableErrorRoot:TraceableError 
 {

Sources/Grammar/Rule/LiteralRule.spf

@@ -1,3 +1,4 @@
+/// A parsing rule that matches terminals against a constant ``Sequence``.
 @retro public
 protocol LiteralRule<Terminal>:ParsingRule
     where Terminal:Equatable, Construction == Void 

Sources/Grammar/Rule/LiteralRule.spf.swift

@@ -1,5 +1,6 @@
 
 #if swift(>=5.7)
+/// A parsing rule that matches terminals against a constant ``Sequence``.
 public
 protocol LiteralRule<Terminal>:ParsingRule
     where Terminal:Equatable, Construction == Void 
@@ -12,6 +13,7 @@ protocol LiteralRule<Terminal>:ParsingRule
     }
 }
 #else 
+/// A parsing rule that matches terminals against a constant ``Sequence``.
 public
 protocol LiteralRule:ParsingRule
     where Terminal:Equatable, Construction == Void 

Sources/Grammar/Rule/ParsingRule.spf

@@ -49,6 +49,13 @@ protocol ParsingRule<Terminal>
 
 extension ParsingRule 
 {
+    /// Attempts to parse the given input completely, emitting diagnostics 
+    /// if parsing failed.
+    ///
+    /// 
+    /// >   Throws: 
+    ///     A ``Pattern/ExpectedEndOfInputError`` if there remained any 
+    ///     unparsed input after applying this rule to its furthest extent.
     @inlinable public static 
     func parse<Source>(diagnosing source:Source) throws -> Construction
         where   Source:Collection, Source.Index == Location, Source.Element == Terminal
@@ -58,6 +65,16 @@ extension ParsingRule
         try input.parse(as: Pattern.End<Location, Terminal>.self)
         return construction
     }
+    /// Attempts to parse the given input completely.
+    /// 
+    /// This method is *not* a default implementation for 
+    /// ``parse(_:)?overload=s7Grammar11ParsingRuleP5parsey12ConstructionQzAA0B5InputVyqd__GzKAA0B11DiagnosticsRd__6Source_5IndexQYd__8LocationRtzAK_7ElementQYd__8TerminalRtzlFZ``; 
+    /// that is a SymbolGraphGen classifier bug.
+    /// 
+    /// To parse with diagnostics, use ``parse(diagnosing:)``.
+    /// >   Throws: 
+    ///     A ``Pattern/ExpectedEndOfInputError`` if there remained any 
+    ///     unparsed input after applying this rule to its furthest extent.
     @inlinable public static 
     func parse<Source>(_ source:Source) throws -> Construction
         where   Source:Collection, Source.Index == Location, Source.Element == Terminal
@@ -67,6 +84,12 @@ extension ParsingRule
         try input.parse(as: Pattern.End<Location, Terminal>.self)
         return construction
     }
+    /// Attempts to parse the given input completely by applying this rule repeatedly.
+    /// 
+    /// This function does not parse with diagnostics.
+    /// >   Throws: 
+    ///     A ``Pattern/ExpectedEndOfInputError`` if there remained any 
+    ///     unparsed input after applying this rule to its furthest extent.
     @inlinable public static 
     func parse<Source, Vector>(_ source:Source, into _:Vector.Type = Vector.self) 
         throws -> Vector

Sources/Grammar/Rule/ParsingRule.spf.swift

@@ -101,6 +101,13 @@ protocol ParsingRule
 
 extension ParsingRule 
 {
+    /// Attempts to parse the given input completely, emitting diagnostics 
+    /// if parsing failed.
+    ///
+    /// 
+    /// >   Throws: 
+    ///     A ``Pattern/ExpectedEndOfInputError`` if there remained any 
+    ///     unparsed input after applying this rule to its furthest extent.
     @inlinable public static 
     func parse<Source>(diagnosing source:Source) throws -> Construction
         where   Source:Collection, Source.Index == Location, Source.Element == Terminal
@@ -110,6 +117,16 @@ extension ParsingRule
         try input.parse(as: Pattern.End<Location, Terminal>.self)
         return construction
     }
+    /// Attempts to parse the given input completely.
+    /// 
+    /// This method is *not* a default implementation for 
+    /// ``parse(_:)?overload=s7Grammar11ParsingRuleP5parsey12ConstructionQzAA0B5InputVyqd__GzKAA0B11DiagnosticsRd__6Source_5IndexQYd__8LocationRtzAK_7ElementQYd__8TerminalRtzlFZ``; 
+    /// that is a SymbolGraphGen classifier bug.
+    /// 
+    /// To parse with diagnostics, use ``parse(diagnosing:)``.
+    /// >   Throws: 
+    ///     A ``Pattern/ExpectedEndOfInputError`` if there remained any 
+    ///     unparsed input after applying this rule to its furthest extent.
     @inlinable public static 
     func parse<Source>(_ source:Source) throws -> Construction
         where   Source:Collection, Source.Index == Location, Source.Element == Terminal
@@ -119,6 +136,12 @@ extension ParsingRule
         try input.parse(as: Pattern.End<Location, Terminal>.self)
         return construction
     }
+    /// Attempts to parse the given input completely by applying this rule repeatedly.
+    /// 
+    /// This function does not parse with diagnostics.
+    /// >   Throws: 
+    ///     A ``Pattern/ExpectedEndOfInputError`` if there remained any 
+    ///     unparsed input after applying this rule to its furthest extent.
     @inlinable public static 
     func parse<Source, Vector>(_ source:Source, into _:Vector.Type = Vector.self) 
         throws -> Vector

Sources/Grammar/Rule/Pattern.swift

@@ -18,7 +18,8 @@ enum Pattern
         {
         }
     }
-
+    /// An integer overflow error occurred while applying one of the 
+    /// built-in integer parsing rules.
     @frozen public
     struct IntegerOverflowError<Integer>:Error, CustomStringConvertible 
         where Integer:FixedWidthInteger
@@ -35,7 +36,7 @@ enum Pattern
             "parsed value overflows integer type '\(Integer.self)'"
         }
     }
-
+    /// An error occured while applying a parsing rule.
     @frozen public
     struct ApplicationError<Rule>:Error, CustomStringConvertible 
         where Rule:ParsingRule 
@@ -50,22 +51,11 @@ enum Pattern
             "expected construction by rule '\(Rule.self)'"
         }
     }
-    @frozen public
-    struct AmbiguityError<Base, Exclusion>:Error, CustomStringConvertible 
-        where Base:ParsingRule, Exclusion:ParsingRule
-    {
-        @inlinable public
-        init()
-        {
-        }
-        public
-        var description:String 
-        {
-            "value of type '\(Base.self)' would also be a valid value of '\(Exclusion.self)'"
-        }
-    }
-
 
+    /// A rule that expects the end of the input. 
+    /// 
+    /// >   Throws: ``ExpectedEndOfInputError`` if there is any 
+    ///     input remaining.
     public
     enum End<Location, Terminal>:ParsingRule 
     {
@@ -81,6 +71,9 @@ enum Pattern
             }
         }
     }
+    /// A rule that unconditionally ignores all remaining input.
+    /// 
+    /// This rule never throws an error.
     public 
     enum Discard<Rule>:ParsingRule 
         where   Rule:ParsingRule, Rule.Construction == Void