Add support for abstract Headerdoc tag #1215
Conversation
binamaniar
changed the title
binamaniar
changed the title
|
@swift-ci please test |
Package.resolved
Outdated
| @@ -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.
done, thank you both. That makes sense.
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.
Package.resolved
Outdated
| @@ -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.
There was a problem hiding this comment.
With the thought of having limited Oxygen/HeaderDoc support I thought we should not restrain from parsing @abstract as an abstract. But open to other ideas too and can be convinced otherwise :)
There was a problem hiding this comment.
I feel like we should at least explore what it would take for @abstract to become the abstract instead of being a sentence in the discussion.
It might also be good to verify that links in the abstract are resolved. IIRC this doesn't happen automatically for new elements.
…s with abstract headerdoc tag retains documentation
binamaniar
force-pushed
the
147920933_abstract_headerdoc_tag
branch
from
13d5c18 to
b28f17e
Compare
| #"\abstract This is description with abstract."#, | ||
| #"\discussion This is a discussion linking to ``doc://unit-test/documentation/ModuleName/AnotherClass`` and ``doc://unit-test/documentation/ModuleName/AnotherClass/prop``."#, |
There was a problem hiding this comment.
What would happen if these two lines were flipped? If the "abstract" content becomes the second sentence in the discussion section, then I'd argue that it's more important that we actually parse @abstract as an abstract (like Vera pointed our here).
There was a problem hiding this comment.
I think it would be a confusing workflow to support in terms of how the abstract is written while documenting, where the first time without tag is abstract, followed by discussion tag, and if there is a abstract tag post that, we would need to append to the abstract in the first line. It is an interesting scenario to think about but I don't know for sure we should support/facilitate that workflow.
|
@swift-ci please test |
|
Merging as-is; we can file additional issues for the abstract related behavior in the future if needed. |
We do need additional functionality. I filed rdar://152423453 to actually parse the |
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