Auto-Capitalize First Word (#880)

emilyychenn · patshaughnessy · web-flow · commit 30110b0f22f7 · 2024-04-15T16:53:41.000+01:00
rdar://122167705

When writing a doc comment, it feels intuitive to not capitalise the first word of its description because of the nature of the doc comment.

For example: adding a new parameter would be written as:
`/// - Parameter testParam: this parameter is just a test parameter to show what this looks like in lowercase.`
In this example, the sentence in doc comments is natural to write with a lowercase starting word, because the first word (Parameter) is already capitalized. 

This PR auto-capitalizes the first word of a new section or aside. Note that this auto-capitalization only occurs if the first word is all lowercase and contains only characters A-Z, or if the first word contains CharacterSet punctuation characters (e.g. a period, comma, hyphen, semi-colon, colon). This capitalization is also locale specific.

---------

Co-authored-by: Pat Shaughnessy &lt;pat_shaughnessy@apple.com&gt;
diff --git a/Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent+Capitalization.swift b/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)
+    }
+}
+
diff --git a/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift b/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] {
diff --git a/Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/DiscussionSectionTranslator.swift b/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)
         }
     }
 }
diff --git a/Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/ParametersSectionTranslator.swift b/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)
                     }
             )
         }
diff --git a/Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/ReturnsSectionTranslator.swift b/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")
         }
     }
 }
diff --git a/Sources/SwiftDocC/Utility/FoundationExtensions/String+Capitalization.swift b/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
+    }
+}
diff --git a/Tests/SwiftDocCTests/Infrastructure/AutoCapitalizationTests.swift b/Tests/SwiftDocCTests/Infrastructure/AutoCapitalizationTests.swift
diff --git a/Tests/SwiftDocCTests/Model/RenderBlockContent+CapitalizationTests.swift b/Tests/SwiftDocCTests/Model/RenderBlockContent+CapitalizationTests.swift
diff --git a/Tests/SwiftDocCTests/Utility/String+CapitalizationTests.swift b/Tests/SwiftDocCTests/Utility/String+CapitalizationTests.swift

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`/*`
`2`	`2`	`This source file is part of the Swift.org open source project`
`3`	`3`
`4`		`- Copyright (c) 2021 Apple Inc. and the Swift project authors`
	`4`	`+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors`
`5`	`5`	`Licensed under Apache License v2.0 with Runtime Library Exception`
`6`	`6`
`7`	`7`	`See https://swift.org/LICENSE.txt for license information`
`@@ -27,6 +27,8 @@ struct DiscussionSectionTranslator: RenderSectionTranslator {`
`27`	`27`	`return nil`
`28`	`28`	`}`
`29`	`29`
	`30`	`+ let capitalizedDiscussionContent = [discussionContent[0].withFirstWordCapitalized] + discussionContent[1...]`
	`31`	`+`
`30`	`32`	`let title: String?`
`31`	`33`	`if let first = discussionContent.first, case RenderBlockContent.heading = first {`
`32`	`34`	`// There's already an authored heading. Don't add another heading.`
`@@ -42,7 +44,7 @@ struct DiscussionSectionTranslator: RenderSectionTranslator {`
`42`	`44`	`}`
`43`	`45`	`}`
`44`	`46`
`45`		`- return ContentRenderSection(kind: .content, content: discussionContent, heading: title)`
	`47`	`+ return ContentRenderSection(kind: .content, content: capitalizedDiscussionContent, heading: title)`
`46`	`48`	`}`
`47`	`49`	`}`
`48`	`50`	`}`