Top level doc comment syntax might be a pit of failure?

Wadler’s law time!

Zig re-uses //! syntax from Rust for “file-level” comments. I’ve observer many times that people routinely working with the language are fine with “if top-level, use //! rather than ///” rule, but newcomers always struggle and use just ///. So, overall it feels a bit like a language footgun.

Zig is already pretty strict about whitespace (eg, it requires ws around binary operators), so I am wondering if we could improve the situation for doc comments. For example,

A /// comment must not be followed by a blank like

i feel could catch a bunch of errors like

/// Here I am trying to document my file

const std = @import("std"); // oups, documented the import instead.

And maybe a bit more radical proposal:

/// can be followed by a blank like only at the start of a container, in which case this would be a top-level comment. //! syntax is removed.

1 Like

A comment with nothing after is already a compile error and a comment with empty newlines between it and the next decl is corrected by zig fmt. I see this as a missing compile error in the compiler.