Improve StringProcessing and RegexBuilder documentation (#611)

This includes documentation improvements for core types/methods, RegexBuilder types along with their generated variadic initializers, and adds some curation. It also includes tests of the documentation code samples.

.gitignore

@@ -93,3 +93,6 @@ fastlane/test_output
 # https://github.com/johnno1962/injectionforxcode
 
 iOSInjectionProject/
+
+# DocC build folder
+*.docc-build

Package.swift

@@ -89,6 +89,14 @@ let package = Package(
  swiftSettings: [
  .unsafeFlags(["-Xfrontend", "-disable-availability-checking"])
  ]),
+ .testTarget(
+ name: "DocumentationTests",
+ dependencies: ["_StringProcessing", "RegexBuilder"],
+ swiftSettings: [
+ .unsafeFlags(["-Xfrontend", "-disable-availability-checking"]),
+ .unsafeFlags(["-enable-bare-slash-regex"]),
+ ]),
+
  // FIXME: Disabled due to rdar://94763190.
  // .testTarget(
  // name: "Prototypes",

Sources/RegexBuilder/Anchor.swift

@@ -147,7 +147,7 @@ extension Anchor {
  ///
  /// Word boundaries are identified using the Unicode default word boundary
  /// algorithm by default. To specify a different word boundary algorithm,
- /// see the `RegexComponent.wordBoundaryKind(_:)` method.
+ /// use the `wordBoundaryKind(_:)` method.
  ///
  /// This anchor is equivalent to `\b` in regex syntax.
  public static var wordBoundary: Anchor {
@@ -157,7 +157,7 @@ extension Anchor {
  /// The inverse of this anchor, which matches at every position that this
  /// anchor does not.
  ///
- /// For the `wordBoundary` and `textSegmentBoundary` anchors, the inverted
+ /// For the ``wordBoundary`` and ``textSegmentBoundary`` anchors, the inverted
  /// version corresponds to `\B` and `\Y`, respectively.
  public var inverted: Anchor {
  var result = self

Sources/RegexBuilder/Builder.swift

@@ -11,6 +11,15 @@
 
 @_spi(RegexBuilder) import _StringProcessing
 
+/// A custom parameter attribute that constructs regular expressions from
+/// closures.
+///
+/// You typically see `RegexComponentBuilder` as a parameter attribute for
+/// `Regex`- or `RegexComponent`-producing closure parameters, allowing those
+/// closures to combine multiple regular expression components. Type
+/// initializers and string algorithm methods in the RegexBuilder framework
+/// include a builder closure parameter, so that you can use regular expression
+/// components together.
 @available(SwiftStdlib 5.7, *)
 @resultBuilder
 public enum RegexComponentBuilder {

Sources/RegexBuilder/CharacterClass.swift

@@ -12,6 +12,11 @@
 @_implementationOnly import _RegexParser
 @_spi(RegexBuilder) import _StringProcessing
 
+/// A class of characters that match in a regex.
+///
+/// A character class can represent individual characters, a group of
+/// characters, the set of character that match some set of criteria, or
+/// a set algebraic combination of all of the above.
 @available(SwiftStdlib 5.7, *)
 public struct CharacterClass {
  internal var ccc: DSLTree.CustomCharacterClass
@@ -42,6 +47,20 @@ extension CharacterClass: RegexComponent {
 
 @available(SwiftStdlib 5.7, *)
 extension CharacterClass {
+ /// A character class that matches any character that does not match this
+ /// character class.
+ ///
+ /// For example, you can use the `inverted` property to create a character
+ /// class that excludes a specific group of characters:
+ ///
+ /// let validCharacters = CharacterClass("a"..."z", .anyOf("-_"))
+ /// let invalidCharacters = validCharacters.inverted
+ ///
+ /// let username = "user123"
+ /// if username.contains(invalidCharacters) {
+ /// print("Invalid username: '\(username)'")
+ /// }
+ /// // Prints "Invalid username: 'user123'"
  public var inverted: CharacterClass {
  if let inv = builtin?.inverted {
  return CharacterClass(builtin: inv)
@@ -53,26 +72,50 @@ extension CharacterClass {
 
 @available(SwiftStdlib 5.7, *)
 extension RegexComponent where Self == CharacterClass {
+ /// A character class that matches any element.
+ ///
+ /// This character class is unaffected by the `dotMatchesNewlines()` method.
+ /// To match any character that isn't a newline, see
+ /// ``anyNonNewline``.
+ ///
+ /// This character class is equivalent to the regex syntax "dot"
+ /// metacharacter in single-line mode: `(?s:.)`.
  public static var any: CharacterClass {
  .init(DSLTree.CustomCharacterClass(members: [.atom(.any)]))
  }
 
+ /// A character class that matches any element that isn't a newline.
+ ///
+ /// This character class is unaffected by the `dotMatchesNewlines()` method.
+ /// To match any character, including newlines, see ``any``.
+ ///
+ /// This character class is equivalent to the regex syntax "dot"
+ /// metacharacter with single-line mode disabled: `(?-s:.)`.
  public static var anyNonNewline: CharacterClass {
  .init(DSLTree.CustomCharacterClass(members: [.atom(.anyNonNewline)]))
  }
 
+ /// A character class that matches any single `Character`, or extended
+ /// grapheme cluster, regardless of the current semantic level.
+ ///
+ /// This character class is equivalent to `\X` in regex syntax.
  public static var anyGraphemeCluster: CharacterClass {
  .init(builtin: .anyGrapheme)
  }
 
- public static var whitespace: CharacterClass {
- .init(builtin: .whitespace)
- }
-
+ /// A character class that matches any digit.
+ ///
+ /// This character class is equivalent to `\d` in regex syntax.
  public static var digit: CharacterClass {
  .init(builtin: .digit)
  }
 
+ /// A character class that matches any hexadecimal digit.
+ ///
+ /// `hexDigit` matches the ASCII characters `0` through `9`, and upper- or
+ /// lowercase `a` through `f`. The corresponding characters in the "Halfwidth
+ /// and Fullwidth Forms" Unicode block are not matched by this character
+ /// class.
  public static var hexDigit: CharacterClass {
  .init(DSLTree.CustomCharacterClass(members: [
  .range(.char("A"), .char("F")),
@@ -81,27 +124,56 @@ extension RegexComponent where Self == CharacterClass {
  ]))
  }
 
+ /// A character class that matches any element that is a "word character".
+ ///
+ /// This character class is equivalent to `\w` in regex syntax.
+ public static var word: CharacterClass {
+ .init(builtin: .word)
+ }
+
+ /// A character class that matches any element that is classified as
+ /// whitespace.
+ ///
+ /// This character class is equivalent to `\s` in regex syntax.
+ public static var whitespace: CharacterClass {
+ .init(builtin: .whitespace)
+ }
+
+ /// A character class that matches any element that is classified as
+ /// horizontal whitespace.
+ ///
+ /// This character class is equivalent to `\h` in regex syntax.
  public static var horizontalWhitespace: CharacterClass {
  .init(builtin: .horizontalWhitespace)
  }
 
+ /// A character class that matches any newline sequence.
+ ///
+ /// This character class is equivalent to `\R` or `\n` in regex syntax.
  public static var newlineSequence: CharacterClass {
  .init(builtin: .newlineSequence)
  }
 
+ /// A character class that matches any element that is classified as
+ /// vertical whitespace.
+ ///
+ /// This character class is equivalent to `\v` in regex syntax.
  public static var verticalWhitespace: CharacterClass {
  .init(builtin: .verticalWhitespace)
  }
-
- public static var word: CharacterClass {
- .init(builtin: .word)
- }
 }
 
 @available(SwiftStdlib 5.7, *)
 extension RegexComponent where Self == CharacterClass {
  /// Returns a character class that matches any character in the given string
  /// or sequence.
+ ///
+ /// Calling this method with a group of characters is equivalent to listing
+ /// those characters in a custom character class in regex syntax. For example,
+ /// the two regexes in this example are equivalent:
+ ///
+ /// let regex1 = /[abcd]+/
+ /// let regex2 = OneOrMore(.anyOf("abcd"))
  public static func anyOf<S: Sequence>(_ s: S) -> CharacterClass
  where S.Element == Character
  {
@@ -111,6 +183,9 @@ extension RegexComponent where Self == CharacterClass {
 
  /// Returns a character class that matches any Unicode scalar in the given
  /// sequence.
+ ///
+ /// Calling this method with a group of Unicode scalars is equivalent to
+ /// listing them in a custom character class in regex syntax.
  public static func anyOf<S: Sequence>(_ s: S) -> CharacterClass
  where S.Element == UnicodeScalar
  {
@@ -122,6 +197,11 @@ extension RegexComponent where Self == CharacterClass {
 // Unicode properties
 @available(SwiftStdlib 5.7, *)
 extension CharacterClass {
+ /// Returns a character class that matches any element with the given Unicode
+ /// general category.
+ ///
+ /// For example, when passed `.uppercaseLetter`, this method is equivalent to
+ /// `/\p{Uppercase_Letter}/` or `/\p{Lu}/`.
  public static func generalCategory(_ category: Unicode.GeneralCategory) -> CharacterClass {
  return CharacterClass(.generalCategory(category))
  }
@@ -148,6 +228,7 @@ public func ...(lhs: UnicodeScalar, rhs: UnicodeScalar) -> CharacterClass {
 
 @available(SwiftStdlib 5.7, *)
 extension RegexComponent where Self == CharacterClass {
+ /// Creates a character class that combines the given classes in a union.
  public init(_ first: CharacterClass, _ rest: CharacterClass...) {
  if rest.isEmpty {
  self.init(first.ccc)
@@ -161,24 +242,29 @@ extension RegexComponent where Self == CharacterClass {
 
 @available(SwiftStdlib 5.7, *)
 extension CharacterClass {
+ /// Returns a character class from the union of this class and the given class.
  public func union(_ other: CharacterClass) -> CharacterClass {
  CharacterClass(.init(members: [
  .custom(self.ccc),
  .custom(other.ccc)]))
  }
 
+ /// Returns a character class from the intersection of this class and the given class.
  public func intersection(_ other: CharacterClass) -> CharacterClass {
  CharacterClass(.init(members: [
  .intersection(self.ccc, other.ccc)
  ]))
  }
 
+ /// Returns a character class by subtracting the given class from this class.
  public func subtracting(_ other: CharacterClass) -> CharacterClass {
  CharacterClass(.init(members: [
  .subtraction(self.ccc, other.ccc)
  ]))
  }
 
+ /// Returns a character class matching elements in one or the other, but not both,
+ /// of this class and the given class.
  public func symmetricDifference(_ other: CharacterClass) -> CharacterClass {
  CharacterClass(.init(members: [
  .symmetricDifference(self.ccc, other.ccc)