Add preceding newlines before Doxygen commands

[a7medev]

Summary

Formatting for Doxygen commands doesn't add preceding newlines to separate them from other markdown content.

Consider the below markdown:

Does something.

\param x first param

\returns result

Which when parsed with .parseMinimalDoxygen produces the following document structure:

Document
├─ Paragraph
│  └─ Text "Does something."
├─ DoxygenParameter parameter: x
│  └─ Paragraph
│     └─ Text "first param"
└─ DoxygenReturns
   └─ Paragraph
      └─ Text "result"

If we format that document with the default options, the resulting markdown is this:

Does something.\param x first param\returns result

Notice that everything is just once paragraph now which doesn't resemble the initial document.

Instead, we should separate Doxygen commands from other content similar to what's currently done by adding 2 newlines before a Paragraph.

Testing

Here's a simple reproducible example:

import Markdown

let markdown = #"""
    Does something.

    \param x first param

    \returns result
    """#

let document = Document(parsing: markdown, options: [.parseBlockDirectives, .parseMinimalDoxygen])

print(document.format())

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[a7medev]

@swift-ci please test

[a7medev]

@Kyle-Ye @d-ronnqvist @QuietMisdreavus Can someone please assist with the review here? We need this for implementing signature help in SourceKit-LSP.

Thanks in advance. 🙏🏼

[d-ronnqvist]

Do these need a blank line in between or would they parse the same if they were just on their own line (without blank lines in between)?

\abstract ...
\param x ...
\returns ...
...

[a7medev]

They'd parse the same without a blank line.

A non-Doxygen-aware markdown renderer would show them on the same line without the blank line though (and most LSP clients like VS Code aren't Doxygen-aware).

If you don't think this is something swift-markdown needs to handle, would it be okay to add an option to always add a blank between Doxygen commands? If not, what do you recommend?

[QuietMisdreavus]

From what i've been able to see, Doxygen commands (and HeaderDoc tags, which are similar) are usually written without an interleaving newline between commands, especially commands of the same kind like \param. Comparing this behavior "when parsed by a non-Doxygen-aware parser" doesn't seem that important to me, since Doxygen commands are non-standard Markdown to begin with.

I would much rather prefer to see "preceding newlines" as a configurable option, with 1 newline (i.e. without an interleaving blank line) as the default. (Maybe as a toggle, something like "print Doxygen commands as separate paragraphs", where turning it on has the behavior you've written, and leaving it off only prints one newline.) You did find a valuable bug in that we don't print any newlines for Doxygen commands at all, so i would want to make sure that we at least print them correctly.

[a7medev]

@QuietMisdreavus @d-ronnqvist That makes sense. I updated the implementation to control this behavior with an option. Please recheck. 🙏🏼

[d-ronnqvist]

How would this behave with two different parameters? I wouldn't expect that to have blank lines in-between.

[a7medev]

Same reasoning as above.

[a7medev]

@d-ronnqvist I'd appreciate your input on whether we should always use 2 separating lines or not. 🙏🏼

[a7medev]

Hello @d-ronnqvist! Sorry for being noisy, but can you please recheck and let me know what the best course of action here is? 🙏🏼

[a7medev]

@swift-ci please test

[a7medev]

@swift-ci please test