Early implementation of formatting comments with Markdown.

[shawnhyam]

@allevato I wanted to check if this is roughly what you had in mind for comment formatting. Maybe you'd be interested in playing with it a bit. I'm very interested in hearing your thoughts on how you see a feature like this working! A few random thoughts so far:

• Most of the time I really like what it does; and a minority of the time, I really really hate what it does.
• The automatic wrapping and list numbering/formatting is really pleasant.
• Commenting out a block of code will result in that block of code being reflowed and completely mangled.
• Ending lines with \ to force line breaks gets re-rendered as double space , which my editor trims and everything ends up getting reformatted anyway.
• It seems too aggressive for .line comments, but aside from the two issues above it could just be an issue with applying it to an existing codebase. Possibly a separate flag, or maybe individual comment sections could have a way to opt in/out?
• There are also block comments; should they be reformatted? If so, is there a canonical form and/or should this be an option?
• Should end-of-line comments be excluded? They are more difficult to format nicely.
• I noticed some of my projects would really benefit from a different width specification for comments.

[allevato]

Thanks for taking a look at this!

Without looking too much at the implementation yet (since parts are likely to change), here are some of my high-level thoughts:

• Commenting out a block of code will result in that block of code being reflowed and completely mangled.

This alone makes me think we should not consider .line or .block comments at all as candidates for reflow. That would be a frustratingly disastrous experience for users. So that would rule out end-of-line comments as well.

On the other hand, it's easy to rationalize doing this for .docLine and .docBlock comments, because the Swift compiler itself assumes that doc comments are Markdown and parses them as such.

• I noticed some of my projects would really benefit from a different width specification for comments.

I agree with this. My typography-loving side thinks there would be a lot of value to letting the user specify a smaller width, like roughly 66, for comments even if the column limit is more. There are subtleties we'd need to consider, like that we don't mean the comment ends at that column number but rather that its width is no more than that (so a doc comment indented at column 8 could go to column 72, not 66), but we'd still have to make sure it never exceeded the total width. I think the way the code is written now and the way the Markdown library handles reflowing makes that pretty straightforward, but it's still probably better saved for a separate future change, just to keep things scoped tighter.

---

When re-rendering text, how does the Markdown library handle parts of the syntax that might have more than one possible form? For example, if I emphasize with either _underscores_ or *asterisks*, does it canonicalize everything to one form or retain what the user wrote? Likewise for unordered lists: if I write

* Blah
  * blah

- Blah
  - blah

Does it keep the bullets I used or force them all to a single form?

[shawnhyam]

• Commenting out a block of code will result in that block of code being reflowed and completely mangled.

This alone makes me think we should not consider .line or .block comments at all as candidates for reflow. That would be a frustratingly disastrous experience for users. So that would rule out end-of-line comments as well.

I agree. Commented-out code blocks have to be left intact.

• I noticed some of my projects would really benefit from a different width specification for comments.

I agree with this. My typography-loving side thinks there would be a lot of value to letting the user specify a smaller width, like roughly 66, for comments even if the column limit is more. There are subtleties we'd need to consider, like that we don't mean the comment ends at that column number but rather that its width is no more than that (so a doc comment indented at column 8 could go to column 72, not 66), but we'd still have to make sure it never exceeded the total width. I think the way the code is written now and the way the Markdown library handles reflowing makes that pretty straightforward, but it's still probably better saved for a separate future change, just to keep things scoped tighter.

Interesting idea, although it might not make much difference in the end. Worth playing around with though.

When re-rendering text, how does the Markdown library handle parts of the syntax that might have more than one possible form? For example, if I emphasize with either _underscores_ or *asterisks*, does it canonicalize everything to one form or retain what the user wrote? Likewise for unordered lists: if I write

* Blah
  * blah

- Blah
  - blah

Does it keep the bullets I used or force them all to a single form?

They get canonicalized to a single form. Lists get a -, emphasis gets *, etc.

[allevato]

Interesting idea, although it might not make much difference in the end. Worth playing around with though.

Did you have something different in mind? Curious what your thoughts were here.

They get canonicalized to a single form. Lists get a -, emphasis gets *, etc.

That works for me! I was worried lists might get something like *, but I guess since Apple prefers - for their doc tags, that's what they chose to render lists with.

[allevato]

What was the status of this? It was still in Draft mode the last time I checked, so I wasn't sure it was ready for deeper review yet.

[shawnhyam]

@allevato I actually wanted to have a discussion to nail down some of the desired behavior around the edge cases of both doc and regular comments. Things like block comments (with and without ASCII art) and indentation level changes, mixtures of different comment types, etc. What is the best place to discuss topics like this?

[allevato]

I think this PR would be fine to discuss those, especially if the discussion needs to happen in the context of the changes you're making in the PR.