Auto-Capitalize First Word

[emilyychenn]

Bug/issue #: rdar://122167705

Summary

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. See the screenshot below for what this looks like in the built documentation.

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).

Dependencies

N/A

Testing

Add documentation via doc comments with anything after the colon (e.g. a parameter, aside, warning, important, todo, note, throws, returns) written in lowercase, then compile the documentation. The rendered documentation should now include an uppercased first character if the first word in the sentence is all lowercase and/or punctuation belonging to the CharacterSet punctuation characters.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[daniel-grumberg]

I think using CharacterSet.whitespacesAndNewlines would be more robust.

[daniel-grumberg]

Also what does this do if the entire string is just one word? or if there are leading spaces?

[d-ronnqvist]

You could also avoid some temporary allocations by using substring APIs. Something like:

let firstWord = prefix(while: { !$0.isWhitespace })
guard let firstLetter = firstWord.first,
      firstLetter.isLowercase,
      !firstWord.contains(where: \.isUppercase)
else {
    return String(self)
}

[emilyychenn]

Adjusted this to use a combination of this and Daniel's suggestion below to use CharacterSet APIs! Let me know what you think about the new implementation @daniel-grumberg @d-ronnqvist

[daniel-grumberg]

I would love to see some integration testing where we go from the relevant markup with a parameters section to RenderJson and see the feature work end to end.

Additionally, I think having a command line flag to turn this off would be good as well but I wonder what @d-ronnqvist thinks about this.

[patshaughnessy]

I'd refactor the core function capitalizeFirstWord to see if you can avoid extra string allocations in the normal case where the first word is already capitalized. This will be called for all sentences in all doc comments, so it might add up.

[patshaughnessy]

This looks great - thanks a lot for refactoring capitalizeFirstWord to return self most of the time I think that might be a noticeable performance difference.

I just left some coding nitpicks you can clean those up before merging if you agree.

[daniel-grumberg]

LGTM

[emilyychenn]

@swift-ci please test

[d-ronnqvist]

I find the mix of Character and CharacterSet API here confusing. It would be better to stick to one.

This could be either something like

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.contains(where: { $0.isLowercase || $0.isPunctuation }) else {
    return self
}

or something like

guard let firstWordStartIndex = rangeOfCharacter(from: .whitespacesAndNewlines.inverted),
      let firstWordEndIndex = rangeOfCharacter(from: .whitespacesAndNewlines, range: firstWordStartIndex.lowerBound..<endIndex)
else { 
    return self
}
let firstWord = self[firstWordEndIndex.lowerBound..<firstWordEndIndex.lowerBound]

guard firstWord.rangeOfCharacter(from: Self.charactersPreventingWordCapitalization) == nil else {
    return self
}