Is there a way to config the zig fmt so it doesn’t break my doc strings?
When I use zig fmt file.zig on a code like this one:
/// this is the first line.<Space><Space>
/// this is the second line.<Space><Space>
fn main() !void {
}
it turns to
/// this is the first line.
/// this is the second line.
fn main() !void {
}
If it isn’t obvious what happened, it took out the trailing white spaces in the doc comments. Which is a problem, as it is the only way of adding a linebreak in hoverable comments that I have found so far.
Don’t think I agree with that view. It matters if you want the doc system to be used. It’s just not currently used much beyond the (rather light) std docs.
I believe the issue is that there are too many version of markdown, as your hesitation between \ and <br> shows. This will lead to further incompatibilities as slightly different version/implementation of markdown are used by zig users. We can’t embed a lot of things in standard markdown. Having graphs would be an improvement for example.
Zig formatter removes whitespace from the end of comments (well, all lines). This is intentional.
In your case, why not have an empty line if you need a line break? Instead relying on a mystical double space to insert a line break, put in the new lines yourself.
/// this is the first line.
///
/// this is the second line.
///
fn main() !void {}
And markdown expects two newlines to put space between paragraphs or elements. This is standard markdown, so putting in the newlines yourself makes more sense then the two spaces.
like others said, in Markdown, you add an empty new line between two paragraphs.
I will take the chance to shill zift (a fork of the zig formatter), but note it retains the trimming lines end thing. If you’d like to add a config for it yourself (and send a patch for it) you can use that.
There is a difference between two spaces and two newlines, though. In Commonmark, two newlines split paragraphs[1] (i.e. <p>...</p>), while two spaces at the end of a line denote a hard line break[2] inside of a single paragraph (i.e. <br>). Those are two semantically different things.
Significant trailing spaces are even worse than significant leading spaces. It’s an abomination. Use a markdown variant that supports the common-sense trailing \for hard line break.
that could work for programs that generate a doc website from doc comments, but I don’t think the tools used for in-IDE doc comments allow you to simply choose to use a different Markdown dialect…
I was not saying formatting doesn’t matter, just that it doesn’t have to be the best.
I do think zig should fix this, and I do think it should allow you to write good, readable, docs.
But I don’t think it is or should be a priority, as you can still make readable docs at the moment, even if they aren’t as readable as you’d like them to be.
I am aware of this. But, I am hesitant to use it as the doc comment appears too spread out for someone trying to read from the src code. Especially when we are talking about 5+ lines.
There’s usually a difference between a paragraph break and a hard line break: the paragraph break adds extra space between the lines but a hard line break simply breaks the line at that point and the following lines don’t have any additional vertical space. The distinction can be useful sometimes.