[PrintAsObjC] Inline code segments in documentation should remain inline. #6625
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
ChristopherRogers
force-pushed
the
SR-3163-PrintAsObjC-comments-with-inline-code
branch
from
d2e080d to
d261bd2
Compare
ChristopherRogers
force-pushed
the
SR-3163-PrintAsObjC-comments-with-inline-code
branch
from
d261bd2 to
85e9075
Compare
|
Seems reasonable to me, even with the Xcode limitations. @bitjammer, what do you think? @swift-ci Please smoke test |
|
LGTM. We can update Xcode's QuickHelp if need be. If you have the time, let me know if you file a radar re: dropping the |
|
Tests pass, let's take it. Thanks, Christopher! |
|
@bitjammer I wasn't sure if you were talking to me but I filed a radar. rdar://29912323 |
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.
TL;DR: This just fixes the issue with backticks abruptly breaking sentences midway in generated Objective-C documentation; Xcode does not render the text as monospace.
I chose to use
<code>instead of<tt>as suggested in the JIRA issue/Doxygen documentation as it's also supported by Doxygen and is the HTML5 replacement for<tt>and a handful of other tags.While
<code>is supported by Doxygen, Xcode does not render text enclosed in<code>tags in a monospace font. (The tags are recognized (and subsequently ignored) by Xcode, however.) In fact, I couldn't find a way to get Xcode to render a span of text in monospace without resorting to inserting the\ccommand before each word. I considered using backticks instead, as I think backticks are more readable as-is than<code>tags (and the backticks are rendered as-in in Xcode). However, with bold being translated using<em>tags and with that not being correctly rendered in Xcode either, I opted to keep everything uniform and chose the<code>tag.(I also noticed there should probably be some sort of character escaping for Doxygen. For example, "This method parses
<code>tags." would be translated as"This method parses <code><code></code> tags."in Doxygen.)Resolves SR-3163.
(This is my first PR so let me know if I'm forgetting something. I believe CI has to be triggered by someone with commit access.)