[6.2] Strip Leading Whitespace From Symbol Graph Doc Comments #1210
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
patshaughnessy
commented
Apr 30, 2025
patshaughnessy
commented
- Explanation: Work around a Clang compiler issue with parsing Objective-C or C comments that are missing the leading asterisk on each line.
- Scope: Changes the way DocC processes doc comments from symbol graphs.
- Issues: rdar://147354452
- Original PRs: Strip Leading Whitespace From Symbol Graph Doc Comments #1190
- Risk: Medium. This adds code to inspect and possibly mutate all doc comments from all symbol graphs. However, the PR adds some detailed tests, and we performed performance benchmarking while reviewing the original PR.
- Testing: Unit tests covering the important uses cases
- Reviewers: @d-ronnqvist
* Strip the minimum leading whitespace from all doc comments loaded from symbol graphs. This worksaround a Clang compiler issue with parsing comments like this that are missing the leading asterisk: /** Foo's brief description. Foo's discussion. */ ...as opposed to this which Clang does parse properly: /** * Foo's brief description. * * Foo's discussion. */ "Minumum leading whitespace" is defined as: - Find the doc comment line with least amount of leading whitespace. Ignore blank lines during this search. - Remove that number of whitespace chars from all the lines (including blank lines). * Update Sources/SwiftDocC/Model/DocumentationNode.swift Refactor a loop to use `contains(where:)` Co-authored-by: David Rönnqvist <[email protected]> * [String].linesWithoutLeadingWhitespace returns an array of substrings, not strings. * [String].linesWithoutLeadingWhitespace checks for an empty collection before continuing to parse all the lines * Tweak comments --------- Co-authored-by: David Rönnqvist <[email protected]>
|
@swift-ci please test |
PortalPete
reviewed
May 1, 2025
Co-authored-by: Pete Lawrence <[email protected]>
franklinsch
approved these changes
May 2, 2025
|
@swift-ci please test |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.