Jazzy requires newlines in Swift doc comments where Swift/Xcode doesn't

[lilyball]

Jazzy isn't interpreting Swift doc comment directives the same way Xcode does. In particular, Jazzy seems to require a blank line before directives where Xcode doesn't.

For example, with the following declaration:

/// The default `HTTPManager` instance.
/// - SeeAlso: `HTTPManagerConfigurable`.
public let HTTP = HTTPManager(shared: true)

Xcode handles this properly:

But Jazzy doesn't:

jazzy version: 0.6.0

[lilyball]

I also see this occur with - Parameter and - Note directives, and I assume it occurs with every directive.

[jpsim]

Thanks for reporting... this has been brought up before and my reaction then was to close it but now I'm thinking it'd be best to mirror Xcode's semantics.

The reason for this discrepancy is that jazzy (well really redcarpet) requires strict Markdown syntax, whereas Xcode doesn't.

However, I really think the best move here would be to move to using Apple's fork of CommonMark that's used to generate QuickHelp docs to match Xcode's behavior exactly.

[lilyball]

Sounds like a good idea. I definitely think Jazzy should match the parsing of Xcode, because people writing documentation comments will likely be using Xcode for them and will expect Jazzy to match. Using the actual implementation Xcode uses sounds like a good way to get this behavior.

[karapigeon]

I definitely agree with @kballard on this. Has any progress been made?

[jpsim]

There's no doubt about it, if Xcode supports a doc format, we should strive to support it too.

Moving the implementation to CommonMark is still a major project though, and would probably incur some regressions, given that redcarpet supports certain useful non-standard Markdown features that our users rely on, like mixed HTML/Markdown.

[johnfairh]

This has been fixed in master for a while now.