Document comment syntax in language docs

[mdsteele]

Maybe this is silly of me, but the docs never seem to explain the comment syntax anywhere. Sure, the code examples make it immediately clear that // is the single-line comment syntax, but that still leaves me, as a new Zig programmer, with several questions:

• Are there multiline comments (e.g. /* comment */)? If not, why not? If so, what is the syntax, and do they nest?
• If you end a single-line comment with a backslash, does it continue to the next line as in C? (Please no.)
• How do doc comments work and what should they look like? (The only mention of doc comments at all appears to be a note about the behavior of merged error sets.) Looks like they go just before the thing they document, but can you also, say, put one just after a struct field on the same line, or does that not work? What about syntax within the doc comment? Is it Markdown? Are there any format conventions for documenting pre/post-conditions or possible errors/panics or whatever? (I realize of course that some of these questions may not have answers yet until generate html documentation for a library #21 gets sorted.)

All that is to say, it would be nice to have a paragraph early in the docs explaining the comment syntax.

[thejoshwolfe]

the docs still need a lot of work.

here's some immediate answers to your questions:

• a comment starts with // and ends at the next LF byte (end of line). that's all there is to comments in zig.

doc comments don't really do anything yet, as far as i know. so far they're just comments following a convention. the plan is:

• doc comments are comments that start with /// and not ////. multiple doc comments in a row are merged together to form a multiline doc comment. the doc comment documents what immediately follows it.
• doc comments are only allowed to document some things. it will be a compile error to doc comment something unexpected, like the middle of an expression or a non-doc comment.

[bheads]

I would also like to see nested comments supported, check out D's /+ +/ comment blocks.

[thejoshwolfe]

nested comments work now.

code;
// comment
//// nested comment

( ͡° ͜ʖ ͡°)

what we don't have is lexical constructs that span multiple lines, and that's not likely to change. each line of zig code can be tokenized out of context, and /**/-style comments would violate that rule.

[mdsteele]

Thanks for the answers! I'll try to put together a short PR for the docs (assuming that would be welcome).

each line of zig code can be tokenized out of context, and /**/-style comments would violate that rule.

Gotcha, thanks -- that answers my "If not, why not?" question above, and would be a great sentence to add in the docs paragraph I am asking for. (-: (I'm guessing this is also the reason for the weird syntax for multiline strings?)

[thejoshwolfe]

Yes. the multiline string syntax actually does stack in the way i mentioned above, and it's used here:

zig/test/compile_errors.zig

Lines 3279 to 3281 in 5d4a02c

	\\ \\.globl aoeu;
	\\ \\.type aoeu, @function;
	\\ \\.set aoeu, derp;

For both commenting and quoting using the line-prefix syntax, you can naively apply the prefix to every line in question, and it will do what you expect. You can then remove the prefix from each line, and that will also do what you expect.

This guarantee is not true with C/C++/Java/JavaScript/etc style comment syntax. Here's a code example that demonstrates just how difficult it is to get /**/ comments to behave properly. Even if you make an attempt to let them "nest", however that's implemented, this example will still be tricky:

/*
string findComment(String s) {
    int endIndex = find(s, "*/"), startIndex = find(s, "/*");
    return s.substring(startIndex, endIndex);
}
*/

And that's not even trying to obfuscate things, like this:

return a
/* // *///*
//* // *//*
*//*/*/
b
// */
;

In Zig, comments are really simple, and they are easy to work with as long as your text editor has a rectangular/column edit mode.

[brandondrew]

this is really the ideal. it's long past time for all editors to support easily toggling the comment status of multiple lines, and there's no reason for a language to acquire needless complexity to solve a problem that should be solved by editors...