add experimental Doxygen support #497
Conversation
rdar://105848459
|
@swift-ci Please test |
| @@ -35,6 +35,7 @@ public struct ConvertAction: Action, RecreatingContext { | |||
| let inheritDocs: Bool | |||
| let treatWarningsAsErrors: Bool | |||
| let experimentalEnableCustomTemplates: Bool | |||
| let experimentalParseDoxygenCommands: Bool | |||
There was a problem hiding this comment.
I don't think the changes in this file are needed since we're using the global Features.current for all the checks. experimentalEnableCustomTemplates was added prior to the Features struct so it follows a different model.
There was a problem hiding this comment.
The primary reason i added it here was for the ConvertSubcommandTests test, since i was basically copying the other test that set up the device-frame support and wanted to make sure that the actions could be used in the test without generating the "unused variable" warning.
There was a problem hiding this comment.
Sorry, I'm not totally following. The DeviceFrame support example doesn't add a property here, does it? I don't think it's worth adding here if it's just for a test. We can just assert on the command and the feature flags:
XCTAssertTrue(commandWithFlag.experimentalParseDoxygenCommands)
XCTAssertTrue(FeatureFlags.current.isExperimentalDoxygenSupportEnabled)
There was a problem hiding this comment.
It looks like in the time between when i started working on this and when i posted it, the test warning in question has been fixed! 😅 I can take this out.
| /// A user-provided value that is true if experimental Doxygen support should be enabled. | ||
| /// | ||
| /// Defaults to false. | ||
| @Flag(help: "Parse a limited set of Doxygen commands as equivalent DocC markup") |
There was a problem hiding this comment.
| @Flag(help: "Parse a limited set of Doxygen commands as equivalent DocC markup") | |
| @Flag(help: "Parse a limited set of Doxygen commands as equivalent Swift-DocC documentation markup") |
There was a problem hiding this comment.
In the past we've marked these as hidden but I don't have a very strong opinion here either way.
| @Flag(help: "Parse a limited set of Doxygen commands as equivalent DocC markup") | |
| @Flag(help: .hidden) |
| "line" : 49 | ||
| } | ||
| }, | ||
| "text" : "\\param suit The suit of the card." |
There was a problem hiding this comment.
Maybe one of these should use @ just to cover all of our bases?
There was a problem hiding this comment.
That's a good idea, i'll switch one over.
|
@swift-ci Please test |
|
@swift-ci Please test |
Bug/issue #, if applicable: rdar://105848459
Summary
This PR takes the Doxygen support added to Swift-Markdown in swiftlang/swift-markdown#107 and adds it to Swift-DocC behind an experimental flag. By passing
--experimental-parse-doxygen-commandstodocc convertordocc preview,\paramand\returnscommands will be handled as if they were- Parameterand- Returnslist items. This allows users transitioning from a different documentation system that handles Doxygen or HeaderDoc commands to transition to Swift-DocC without needing to change these commands immediately.Dependencies
None (the Swift-Markdown PR is already merged and is being used in this PR)
Testing
Steps:
Tests/SwiftDocCTests/Test Resources/DeckKit-Objective-C.symbols.jsonto a documentation catalog.swift run docc preview MyDocs.docc --experimental-parse-doxygen-commands[PlayingCard newWithRank:ofSuit:]correctly displays "Parameters" and "Return Value" sections instead of the raw\paramand\returnscommand lines.Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded