Revise doc comments for API reference style.

- Fix spelling error in parameter name (invertion --> inversion).
- Add docs for parameters and return values.
- Use indicative instead of imperative for method/function/initializer
  abstracts.  (Match a regex. --> Matches a regex.)
- Don't use code voice in abstracts, or symbol names as English nouns.
- Use contractions per Apple style.
- Turn /// comments that contain notes for this API's implementers into
  plain // comments, to omit that content from the docs.  Move them
  before the /// comments, to keep doc comments immediately adjacent
  to the declaration they documents.

Author: amartini51

Sources/RegexBuilder/CharacterClass.swift

@@ -100,7 +100,7 @@ extension RegexComponent where Self == CharacterClass {
       members: s.map { .atom(.char($0)) }))
   }
 
-  /// Returns a character class that matches any unicode scalar in the given
+  /// Returns a character class that matches any Unicode scalar in the given
   /// sequence.
   public static func anyOf<S: Sequence>(_ s: S) -> CharacterClass
     where S.Element == UnicodeScalar
@@ -118,15 +118,15 @@ extension CharacterClass {
   }
 }
 
-/// Range syntax for characters in `CharacterClass`es.
+/// Returns a character class that includes the characters in the given range.
 @available(SwiftStdlib 5.7, *)
 public func ...(lhs: Character, rhs: Character) -> CharacterClass {
   let range: DSLTree.CustomCharacterClass.Member = .range(.char(lhs), .char(rhs))
   let ccc = DSLTree.CustomCharacterClass(members: [range], isInverted: false)
   return CharacterClass(ccc)
 }
 
-/// Range syntax for unicode scalars in `CharacterClass`es.
+/// Returns a character class that includes the Unicode scalars in the given range.
 @_disfavoredOverload
 @available(SwiftStdlib 5.7, *)
 public func ...(lhs: UnicodeScalar, rhs: UnicodeScalar) -> CharacterClass {

Sources/RegexBuilder/DSL.swift

@@ -95,8 +95,8 @@ extension UnicodeScalar: RegexComponent {
 // Note: Quantifiers are currently gyb'd.
 
 extension DSLTree.Node {
-  /// Generates a DSLTree node for a repeated range of the given DSLTree node.
-  /// Individual public API functions are in the generated Variadics.swift file.
+  // Individual public API functions are in the generated Variadics.swift file.
+  /// Generates a DSL tree node for a repeated range of the given node.
   @available(SwiftStdlib 5.7, *)
   static func repeating(
     _ range: Range<Int>,
@@ -251,8 +251,10 @@ public struct TryCapture<Output>: _BuiltinRegexComponent {
 
 // MARK: - Groups
 
-/// An atomic group, i.e. opens a local backtracking scope which, upon successful exit,
-/// discards any remaining backtracking points from within the scope
+/// An atomic group.
+///
+/// This group opens a local backtracking scope which, upon successful exit,
+/// discards any remaining backtracking points from within the scope.
 @available(SwiftStdlib 5.7, *)
 public struct Local<Output>: _BuiltinRegexComponent {
   public var regex: Regex<Output>
@@ -265,6 +267,7 @@ public struct Local<Output>: _BuiltinRegexComponent {
 // MARK: - Backreference
 
 @available(SwiftStdlib 5.7, *)
+/// A backreference.
 public struct Reference<Capture>: RegexComponent {
   let id = ReferenceID()
 

Sources/_RegexParser/Regex/AST/AST.swift

@@ -9,8 +9,9 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A regex abstract syntax tree. This is a top-level type that stores the root
-/// node.
+/// A regex abstract syntax tree.
+///
+/// This is a top-level type that stores the root node.
 public struct AST: Hashable {
   public var root: AST.Node
   public var globalOptions: GlobalMatchingOptionSequence?
@@ -22,7 +23,7 @@ public struct AST: Hashable {
 }
 
 extension AST {
-  /// Whether this AST tree has nested somewhere inside it a capture.
+  /// Whether this AST tree contains at least one capture nested inside of it.
   public var hasCapture: Bool { root.hasCapture }
 
   /// The capture structure of this AST tree.
@@ -94,7 +95,9 @@ extension AST.Node {
     _associatedValue as? T
   }
 
-  /// If this node is a parent node, access its children
+  /// The child nodes of this node.
+  ///
+  /// If the node isn't a parent node, this value is `nil`.
   public var children: [AST.Node]? {
     return (_associatedValue as? _ASTParent)?.children
   }
@@ -103,15 +106,15 @@ extension AST.Node {
     _associatedValue.location
   }
 
-  /// Whether this node is "trivia" or non-semantic, like comments
+  /// Whether this node is trivia or non-semantic, like comments.
   public var isTrivia: Bool {
     switch self {
     case .trivia: return true
     default: return false
     }
   }
 
-  /// Whether this node has nested somewhere inside it a capture
+  /// Whether this node contains at least one capture nested inside of it.
   public var hasCapture: Bool {
     switch self {
     case .group(let g) where g.kind.value.isCapturing:
@@ -122,7 +125,7 @@ extension AST.Node {
     return self.children?.any(\.hasCapture) ?? false
   }
 
-  /// Whether this AST node may be used as the operand of a quantifier such as
+  /// Whether this node may be used as the operand of a quantifier such as
   /// `?`, `+` or `*`.
   public var isQuantifiable: Bool {
     switch self {
@@ -203,7 +206,9 @@ extension AST {
     }
   }
 
-  /// An Oniguruma absent function. This is used to model a pattern which should
+  /// An Oniguruma absent function.
+  ///
+  /// This is used to model a pattern which should
   /// not be matched against across varying scopes.
   public struct AbsentFunction: Hashable, _ASTNode {
     public enum Start: Hashable {

Sources/_RegexParser/Regex/AST/Atom.swift

@@ -415,7 +415,7 @@ extension AST.Atom.CharacterProperty {
 }
 
 extension AST.Atom {
-  /// Anchors and other built-in zero-width assertions
+  /// Anchors and other built-in zero-width assertions.
   @frozen
   public enum AssertionKind: String {
     /// \A
@@ -574,7 +574,7 @@ extension AST.Atom {
 }
 
 extension AST.Atom.Callout {
-  /// A tag specifier `[...]` which may appear in an Oniguruma callout.
+  /// A tag specifier `[...]` that can appear in an Oniguruma callout.
   public struct OnigurumaTag: Hashable {
     public var leftBracket: SourceLocation
     public var name: AST.Located<String>
@@ -668,8 +668,10 @@ extension AST.Atom.EscapedBuiltin {
 }
 
 extension AST.Atom {
-  /// Retrieve the character value of the atom if it represents a literal
-  /// character or unicode scalar, nil otherwise.
+  /// Retrieves the character value of the atom.
+  ///
+  /// If the atom doesn't represent a literal character or a Unicode scalar,
+  /// this value is `nil`.
   public var literalCharacterValue: Character? {
     switch kind {
     case .char(let c):
@@ -711,9 +713,9 @@ extension AST.Atom {
     }
   }
 
-  /// Produce a string literal representation of the atom, if possible
+  /// A string literal representation of the atom, if possible.
   ///
-  /// Individual characters will be returned, Unicode scalars will be
+  /// Individual characters are returned as-is, and Unicode scalars are
   /// presented using "\u{nnnn}" syntax.
   public var literalStringValue: String? {
     switch kind {

Sources/_RegexParser/Regex/AST/CustomCharClass.swift

@@ -104,8 +104,9 @@ extension CustomCC.Member {
 }
 
 extension AST.CustomCharacterClass {
-  /// Strip trivia from the character class members. This does not recurse into
-  /// nested custom character classes.
+  /// Strips trivia from the character class members.
+  ///
+  /// This method doesn't recurse into nested custom character classes.
   public var strippingTriviaShallow: Self {
     var copy = self
     copy.members = copy.members.filter(\.isSemantic)

Sources/_RegexParser/Regex/AST/Group.swift

@@ -78,14 +78,17 @@ extension AST {
 }
 
 extension AST.Group.Kind {
+  /// Whether the group is a capturing group.
   public var isCapturing: Bool {
     switch self {
     case .capture, .namedCapture, .balancedCapture: return true
     default: return false
     }
   }
 
-  /// If this is a named group, its name, `nil` otherwise.
+  /// The name of the group.
+  ///
+  /// If the group doesn't have a name, this value is `nil`.
   public var name: String? {
     switch self {
     case .namedCapture(let name): return name.value
@@ -96,9 +99,11 @@ extension AST.Group.Kind {
 }
 
 extension AST.Group.Kind {
-  /// If this group is a lookaround assertion, return its direction
-  /// and whether it is positive or negative. Otherwise returns
-  /// `nil`.
+  /// The direction of a lookaround assertion
+  /// and an indication of whether the assertion is positive or negative.
+  ///
+  /// If the group isn't a lookaheand or lookbehind assertion,
+  /// this value is `nil`.
   public var lookaroundKind: (forwards: Bool, positive: Bool)? {
     switch self {
     case .lookahead:         return (true, true)

Sources/_RegexParser/Regex/AST/MatchingOptions.swift

@@ -10,7 +10,7 @@
 //===----------------------------------------------------------------------===//
 
 extension AST {
-  /// An option written in source that changes matching semantics.
+  /// An option, written in source, that changes matching semantics.
   public struct MatchingOption: Hashable {
     public enum Kind {
       // PCRE options
@@ -83,7 +83,7 @@ extension AST {
     }
   }
 
-  /// A sequence of matching options written in source.
+  /// A sequence of matching options, written in source.
   public struct MatchingOptionSequence: Hashable {
     /// If the sequence starts with a caret '^', its source location, or nil
     /// otherwise. If this is set, it indicates that all the matching options
@@ -138,8 +138,11 @@ extension AST.MatchingOptionSequence: _ASTPrintable {
 }
 
 extension AST {
-  /// Global matching option specifiers. Unlike `MatchingOptionSequence`,
-  /// these must appear at the start of the pattern, and apply globally.
+  /// Global matching option specifiers.
+  ///
+  /// Unlike `MatchingOptionSequence`,
+  /// these options must appear at the start of the pattern,
+  /// and they apply to the entire pattern.
   public struct GlobalMatchingOption: _ASTNode, Hashable {
     /// Determines the definition of a newline for the '.' character class and
     /// when parsing end-of-line comments.

Sources/_RegexParser/Regex/AST/Quantification.swift

@@ -59,7 +59,7 @@ extension AST {
 /// MARK: - Semantic API
 
 extension AST.Quantification.Amount {
-  /// Get the bounds
+  /// The bounds.
   public var bounds: (atLeast: Int, atMost: Int?) {
     switch self {
     case .zeroOrMore: return (0, nil)

Sources/_RegexParser/Regex/Parse/CaptureStructure.swift

@@ -286,10 +286,11 @@ extension CaptureStructure {
     MemoryLayout<SerializationVersion>.stride + inputUTF8CodeUnitCount + 1
   }
 
-  /// Encode the capture structure to the given buffer as a serialized
+  /// Encodes the capture structure to the given buffer as a serialized
   /// representation.
   ///
   /// The encoding rules are as follows:
+  ///
   /// ```
   /// encode(〚`T`〛) ==> <version>, 〚`T`〛, .end
   /// 〚`T` (atom)〛 ==> .atom

Sources/_RegexParser/Regex/Parse/Parse.swift

@@ -577,8 +577,8 @@ fileprivate func defaultSyntaxOptions(
   }
 }
 
-/// Parse a given regex string with delimiters, inferring the syntax options
-/// from the delimiter used.
+/// Parses a given regex string with delimiters, inferring the syntax options
+/// from the delimiters used.
 public func parseWithDelimiters<S: StringProtocol>(
   _ regex: S
 ) throws -> AST where S.SubSequence == Substring {