Add support for abstract Headerdoc tag #1215
Conversation
binamaniar
changed the title
binamaniar
changed the title
|
@swift-ci please test |
| @@ -5,17 +5,17 @@ | |||
| "kind" : "remoteSourceControl", | |||
| "location" : "https://github.com/apple/swift-argument-parser.git", | |||
| "state" : { | |||
| "revision" : "0fbc8848e389af3bb55c182bc19ca9d5dc2f255b", | |||
| "version" : "1.4.0" | |||
| "revision" : "41982a3656a71c768319979febd796c6fd111d5c", | |||
There was a problem hiding this comment.
Should we avoid updating all the dependencies? Maybe we should just update the one new version of swift-markdown below. Or do we typically run swift package update and update everything when possible?
There was a problem hiding this comment.
Usually with a paired PR like this, we should only run swift package update swift-markdown to only pull in Swift-Markdown specifically, and leave the other dependencies alone.
There was a problem hiding this comment.
This looks good, though i would prefer if you could reset the Package.resolved and only run swift package resolve or swift package update swift-markdown when you update the branch back, so it only updates Swift-Markdown and swift-cmark.
My other comment is more of a curiosity. I think this PR can land as-is just so the content is properly rendered somehow, even if it's not as an abstract per se.
| @@ -5,17 +5,17 @@ | |||
| "kind" : "remoteSourceControl", | |||
| "location" : "https://github.com/apple/swift-argument-parser.git", | |||
| "state" : { | |||
| "revision" : "0fbc8848e389af3bb55c182bc19ca9d5dc2f255b", | |||
| "version" : "1.4.0" | |||
| "revision" : "41982a3656a71c768319979febd796c6fd111d5c", | |||
There was a problem hiding this comment.
Usually with a paired PR like this, we should only run swift package update swift-markdown to only pull in Swift-Markdown specifically, and leave the other dependencies alone.
| XCTAssertEqual(overviewSection.content, [ | ||
| .heading(.init(level: 2, text: "Overview", anchor: "overview")), | ||
|
|
||
| .paragraph(.init(inlineContent: [.text("This is description with abstract.")])), |
There was a problem hiding this comment.
Should we try to actually parse @abstract as an abstract? I feel like it would stay true to the use of the command.
On the other hand, we probably shouldn't add too much Doxygen/HeaderDoc support, since we really want to push people to using Markdown... 😅 I'm fine either way on this, though i'm curious what the workgroup (or just the rest of our team) thinks.
…s with abstract headerdoc tag retains documentation
binamaniar
force-pushed
the
147920933_abstract_headerdoc_tag
branch
from
13d5c18 to
b28f17e
Compare
Bug/issue #, if applicable: rdar://147920933
Summary
This note adds support for Doxygen @abstract tag. Abstract tags are turned into normal paragraphs.
Dependencies
Swift-markdown dependency swiftlang/swift-markdown#227
Testing
Create a documentation comment containing @abstract
This is an overview.
@abstract this is the content for abstract tag
Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded