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.