Add rule to "add space between '//' and beginning of comment"

[ErciliaR]

Add rule to "add space between '//' and beginning of comment"

[HassanTaleb90]

Comments are entirely up to the user, sometimes the user prefers to put one space and sometimes two spaces in the same file.

Example:

So in my opinion we should not control it.

@ErciliaR

[natikgadzhi]

@HassanTaleb90 @allevato, in some situations for structured comments (DocC) format does affect how they would parse and get processed. Wrong formatting of a doc comment might result in broken documentation.

That would be a different rule from the one @ErciliaR suggests here. There must've been another discussion on this that I missed — feel free to "well actually" and link me to it!

I wonder, how do we make decisions about adding rules? They're optional, so in theory, we can provide a rule that enforces one and only one space between // and the comment text. How do we decide whether we add it or not? Any way we can survey our users, see what people use in the wild?

[allevato]

I assumed that this issue is presumably about non-documentation comments, so at the risk of digressing...

For documentation comments, users should be authoring valid Markdown. Period. If the comment is structurally valid, then rewrapping it using the Markdown module should not result in broken documentation, even if we change its indentation or where the lines wrap. In my opinion, if someone writes documentation comments that aren't valid Markdown/DocC, they shouldn't expect them to be handled correctly by the formatter, because they're already not handled correctly by other tools (the compiler itself parses them to generate .swiftdoc files, SourceKit uses them to show help in the IDE, DocC uses them to generate documentation).

However, I'm not sure how opinionated we want to be about documentation comments. We already use the Markdown APIs to extract comments and analyze them, but I haven't sat down with those APIs long enough to determine how much it preserves or doesn't preserve markup choices if you take Markdown text, parse it, and then rerender it as Markdown. For example, when you have multiple choices like _foo_ and *foo*, does it preserve those or does it always render one or the other? What about bulleted lists? Indented code blocks vs. fenced code blocks?

It all depends on how prescriptive we want to be with the markup choices and how flexible those APIs are.

[ahoppen]

Tracked in Apple’s issue tracker as rdar://126948292