Wadler’s law time!
//! 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,
///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.