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. 🙏🏼

[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

[a7medev]

Hello @d-ronnqvist @QuietMisdreavus! Have you got a chance to check the updated changes?

[a7medev]

@QuietMisdreavus @d-ronnqvist Friendly reminder.

[QuietMisdreavus]

This looks great, thanks for reworking it!

[QuietMisdreavus]

There's a command-line tool that exposes a hook to MarkupFormatter in Tools/markdown-tool, but it looks like it wasn't updated for the doxygenCommandPrefix option either, so i'll go ahead and merge this PR without that. Thanks again!