Add docCommentValue property to Trivia

[PhantomInTheWire]

fixes: #1890

• Adds Trivia.docCommentValue to conveniently extract the text content of the last documentation comment in a trivia collection.
• Automatically strips comment markers (///, /**, */) and intelligently removes common indentation from multi-line block comments.
• Implements stateful parsing to correctly handle section breaks, ensuring only the most immediate doc comment is processed.
• Includes extensive test coverage for various scenarios including mixed comment styles, complex indentation, and interleaved non-doc trivia.

[ahoppen]

If I understand it correctly, this PR is based on top of #2966, right? Thanks for picking that stale PR up! To make sure we give @zyadtaha credit where credit is due for all the work he put into the original PR, would you mind basing you changes on top of his branch so that we retain his original commit and keep him listed as that commit’s author? The author field should be retained if you cherry-pick a commit or rebase it (feel free to read up on the distinction between committer and author in git if you are interested 😉).

A real review will follow, I think it might be easier to get the git logistics sorted out first though.

[PhantomInTheWire]

@ahoppen I think this should be good now

[ahoppen]

Thanks for picking the PR up again, @PhantomInTheWire

[ahoppen]

Just two style comments, otherwise LGTM.

[PhantomInTheWire]

@swift-ci please test

[PhantomInTheWire]

@swift-ci test macos

[PhantomInTheWire]

@swift-ci test linux

[ahoppen]

LGTM. I forgot a little bit that this is swift-syntax and we haven an RFC process for adding/changing public API. Could you create a forum post as described in there to allow others to weigh in? Once that’s done, we can hit merge. Any potential feedback can be addressed in follow-up PRs.

[PhantomInTheWire]

@swift-ci please test macos

[PhantomInTheWire]

RFC: https://forums.swift.org/t/rfc-add-trivia-doccommentvalue-property/84192