Auto-Capitalize First Word

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent+Capitalization.swift

@@ -0,0 +1,92 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2024 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+/// For auto capitalizing the first letter of a sentence following a colon (e.g. asides, sections such as parameters, returns).
+protocol AutoCapitalizable {
+
+    /// Any type that conforms to the AutoCapitalizable protocol will have the first letter of the first word capitalized (if applicable).
+    var withFirstWordCapitalized: Self {
+        get
+    }
+
+}
+
+extension AutoCapitalizable {
+    var withFirstWordCapitalized: Self { return self }
+}
+
+extension RenderInlineContent: AutoCapitalizable {
+    /// Capitalize the first word for normal text content, as well as content that has emphasis or strong applied.
+    var withFirstWordCapitalized: Self {
+        switch self {
+        case .text(let text):
+            return .text(text.capitalizeFirstWord())
+        case .emphasis(inlineContent: let embeddedContent):
+            return .emphasis(inlineContent: [embeddedContent[0].withFirstWordCapitalized] + embeddedContent[1...])
+        case .strong(inlineContent: let embeddedContent):
+            return .strong(inlineContent: [embeddedContent[0].withFirstWordCapitalized] + embeddedContent[1...])
+        default:
+            return self
+        }
+    }
+}
+
+
+extension RenderBlockContent: AutoCapitalizable {
+    /// Capitalize the first word for paragraphs, asides, headings, and small content.
+    var withFirstWordCapitalized: Self {
+        switch self {
+        case .paragraph(let paragraph):
+            return .paragraph(paragraph.withFirstWordCapitalized)
+        case .aside(let aside):
+            return .aside(aside.withFirstWordCapitalized)
+        case .small(let small):
+            return .small(small.withFirstWordCapitalized)
+        case .heading(let heading):
+            return .heading(.init(level: heading.level, text: heading.text.capitalizeFirstWord(), anchor: heading.anchor))
+        default:
+            return self
+        }
+    }
+}
+
+extension RenderBlockContent.Paragraph: AutoCapitalizable {
+    var withFirstWordCapitalized: RenderBlockContent.Paragraph {
+        guard !self.inlineContent.isEmpty else {
+            return self
+        }
+
+        let inlineContent = [self.inlineContent[0].withFirstWordCapitalized] + self.inlineContent[1...]
+        return .init(inlineContent: inlineContent)
+    }
+}
+
+extension RenderBlockContent.Aside: AutoCapitalizable {
+    var withFirstWordCapitalized: RenderBlockContent.Aside {
+        guard !self.content.isEmpty else {
+            return self
+        }
+
+        let content = [self.content[0].withFirstWordCapitalized] + self.content[1...]
+        return .init(style: self.style, content: content)
+    }
+}
+
+extension RenderBlockContent.Small: AutoCapitalizable {
+    var withFirstWordCapitalized: RenderBlockContent.Small {
+        guard !self.inlineContent.isEmpty else {
+            return self
+        }
+
+        let inlineContent = [self.inlineContent[0].withFirstWordCapitalized] + self.inlineContent[1...]
+        return .init(inlineContent: inlineContent)
+    }
+}
+

Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

@@ -36,8 +36,13 @@ struct RenderContentCompiler: MarkupVisitor {
 
     mutating func visitBlockQuote(_ blockQuote: BlockQuote) -> [RenderContent] {
         let aside = Aside(blockQuote)
-        return [RenderBlockContent.aside(.init(style: RenderBlockContent.AsideStyle(asideKind: aside.kind),
-                                               content: aside.content.reduce(into: [], { result, child in result.append(contentsOf: visit(child))}) as! [RenderBlockContent]))]
+
+        let newAside = RenderBlockContent.Aside(
+            style: RenderBlockContent.AsideStyle(asideKind: aside.kind),
+            content: aside.content.reduce(into: [], { result, child in result.append(contentsOf: visit(child))}) as! [RenderBlockContent]
+        )
+
+        return [RenderBlockContent.aside(newAside.withFirstWordCapitalized)]
     }
 
     mutating func visitCodeBlock(_ codeBlock: CodeBlock) -> [RenderContent] {

Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/DiscussionSectionTranslator.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -27,6 +27,8 @@ struct DiscussionSectionTranslator: RenderSectionTranslator {
                 return nil
             }
 
+            let capitalizedDiscussionContent = [discussionContent[0].withFirstWordCapitalized] + discussionContent[1...]
+
             let title: String?
             if let first = discussionContent.first, case RenderBlockContent.heading = first {
                 // There's already an authored heading. Don't add another heading.
@@ -42,7 +44,7 @@ struct DiscussionSectionTranslator: RenderSectionTranslator {
                 }
             }
 
-            return ContentRenderSection(kind: .content, content: discussionContent, heading: title)
+            return ContentRenderSection(kind: .content, content: capitalizedDiscussionContent, heading: title)
         }
     }
 }

Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/ParametersSectionTranslator.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -28,7 +28,14 @@ struct ParametersSectionTranslator: RenderSectionTranslator {
                         let parameterContent = renderNodeTranslator.visitMarkupContainer(
                             MarkupContainer(parameter.contents)
                         ) as! [RenderBlockContent]
-                        return ParameterRenderSection(name: parameter.name, content: parameterContent)
+
+                        guard !parameterContent.isEmpty else {
+                            return ParameterRenderSection(name: parameter.name, content: parameterContent)
+                        }
+
+                        let capitalizedParameterContent = [parameterContent[0].withFirstWordCapitalized] + parameterContent[1...]
+
+                        return ParameterRenderSection(name: parameter.name, content: capitalizedParameterContent)
                     }
             )
         }

Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/ReturnsSectionTranslator.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -28,7 +28,9 @@ struct ReturnsSectionTranslator: RenderSectionTranslator {
                 return nil
             }
 
-            return ContentRenderSection(kind: .content, content: returnsContent, heading: "Return Value")
+            let capitalizedReturnsContent = [returnsContent[0].withFirstWordCapitalized] + returnsContent[1...]
+
+            return ContentRenderSection(kind: .content, content: capitalizedReturnsContent, heading: "Return Value")
         }
     }
 }

Sources/SwiftDocC/Utility/FoundationExtensions/String+Capitalization.swift

@@ -0,0 +1,38 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2024 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+
+extension String {
+
+    // Precomputes the CharacterSet to use in capitalizeFirstWord().
+    private static let charactersPreventingWordCapitalization = CharacterSet.lowercaseLetters.union(.punctuationCharacters).inverted
+
+    /// Returns the string with the first letter capitalized.
+    /// This auto-capitalization only occurs if the first word is all lowercase and contains only lowercase letters.
+    /// The first word can also contain punctuation (e.g. a period, comma, hyphen, semi-colon, colon).
+    func capitalizeFirstWord() -> String {
+        guard let firstWordStartIndex = self.firstIndex(where: { !$0.isWhitespace && !$0.isNewline }) else { return self }
+        let firstWord = self[firstWordStartIndex...].prefix(while: { !$0.isWhitespace && !$0.isNewline})
+
+        guard firstWord.rangeOfCharacter(from: Self.charactersPreventingWordCapitalization) == nil else {
+            return self
+        }
+
+        var resultString = String() 
+        resultString.reserveCapacity(self.count)
+        resultString.append(contentsOf: self[..<firstWordStartIndex])
+        resultString.append(contentsOf: String(firstWord).localizedCapitalized)
+        let restStartIndex = self.index(firstWordStartIndex, offsetBy: firstWord.count)
+        resultString.append(contentsOf: self[restStartIndex...])
+
+        return resultString
+    }
+}