Merge pull request #350 from apple/amartini/docs_91301229

Revise doc comments for API reference style.

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 {

Sources/_RegexParser/Regex/Parse/Source.swift

@@ -9,10 +9,12 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// The source given to a parser. This can be bytes in memory, a file on disk,
-/// something streamed over a network connection, etc.
+// For now, we use String as the source while prototyping...
+
+/// The source of text being given to a parser.
 ///
-/// For now, we use String...
+/// This can be bytes in memory, a file on disk,
+/// something streamed over a network connection, and so on.
 ///
 public struct Source {
   var input: Input
@@ -37,7 +39,7 @@ extension Source {
   public typealias Input = String    // for wrapper...
   public typealias Char  = Character // for wrapper...
 
-  /// A precise point in the input, commonly used for bounded ranges
+  /// A precise point in the input, commonly used for bounded ranges.
   public typealias Position = String.Index
 }
 

Sources/_RegexParser/Regex/Parse/SourceLocation.swift

@@ -62,7 +62,7 @@ public protocol LocatedErrorProtocol: Error {
 }
 
 extension Source {
-  /// An error with source location info
+  /// An error that includes information about the location in source code.
   public struct LocatedError<E: Error>: Error, LocatedErrorProtocol {
     public let error: E
     public let location: SourceLocation
@@ -77,10 +77,10 @@ extension Source {
     }
   }
 
-  /// Located value: a value wrapped with a source range
+  /// A value wrapped with a source range.
   ///
-  /// Note: source location is part of value identity, so that the same
-  /// e.g. `Character` appearing twice can be stored in a data structure
+  /// Note: Source location is part of value identity so that, for example, the
+  /// same `Character` value appearing twice can be stored in a data structure
   /// distinctly. To ignore source locations, use `.value` directly.
   public struct Located<T> {
     public var value: T

Sources/_RegexParser/Regex/Parse/SyntaxOptions.swift

@@ -31,31 +31,31 @@ public struct SyntaxOptions: OptionSet {
     [.endOfLineComments, .nonSemanticWhitespace]
   }
 
+  // NOTE: Currently, this means we have raw quotes.
+  // Better would be to have real Swift string delimiter parsing logic.
+
   /// `'a "." b' == '/a\Q.\Eb/'`
-  ///
-  /// NOTE: Currently, this means we have raw quotes.
-  /// Better would be to have real Swift string delimiter parsing logic.
   public static var experimentalQuotes: Self { Self(1 << 2) }
 
+  // NOTE: traditional comments are not nested. Currently, we are neither.
+  // Traditional comments can't have `)`, not even escaped in them either, we
+  // can. Traditional comments can have `*/` in them, we can't without
+  // escaping. We don't currently do escaping.
+
   /// `'a /* comment */ b' == '/a(?#. comment )b/'`
-  ///
-  /// NOTE: traditional comments are not nested. Currently, we are neither.
-  /// Traditional comments can't have `)`, not even escaped in them either, we
-  /// can. Traditional comments can have `*/` in them, we can't without
-  /// escaping. We don't currently do escaping.
   public static var experimentalComments: Self { Self(1 << 3) }
 
   /// ```
-  ///   'a{n...m}' == '/a{n,m}/'
-  ///   'a{n..<m}' == '/a{n,m-1}/'
-  ///   'a{n...}'  == '/a{n,}/'
-  ///   'a{...m}'  == '/a{,m}/'
-  ///   'a{..<m}'  == '/a{,m-1}/'
+  /// 'a{n...m}' == '/a{n,m}/'
+  /// 'a{n..<m}' == '/a{n,m-1}/'
+  /// 'a{n...}'  == '/a{n,}/'
+  /// 'a{...m}'  == '/a{,m}/'
+  /// 'a{..<m}'  == '/a{,m-1}/'
   /// ```
   public static var experimentalRanges: Self { Self(1 << 4) }
 
   /// `(name: .*)` == `(?<name>.*)`
-  ///  `(_: .*)` == `(?:.*)`
+  /// `(_: .*)` == `(?:.*)`
   public static var experimentalCaptures: Self { Self(1 << 5) }
 
   /// The default syntax for a multi-line regex literal.

Sources/_RegexParser/Regex/Printing/DumpAST.swift

@@ -9,10 +9,11 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// AST entities can be pretty-printed or dumped
+/// AST entities that can be pretty-printed or dumped.
 ///
-/// Alternative: just use `description` for pretty-print
-/// and `debugDescription` for dump
+/// As an alternative to this protocol,
+/// you can also use the `description` to pretty-print an AST,
+/// and `debugDescription` for to dump a debugging representation.
 public protocol _ASTPrintable:
   CustomStringConvertible,
   CustomDebugStringConvertible