Proposal: Module-level doc comments

[nmichaels]

The current documentation for doc comments states that

The doc comment documents whatever immediately follows it.

and

Doc comments are only allowed in certain places; eventually, it will become a compile error to have a doc comment in an unexpected place, such as in the middle of an expression, or just before a non-doc comment.

I'd like to propose that this is extended to include module-level doc comments at the beginning of a file. Sometimes it's desirable to have a top-level description of how a library is intended to be used, apart from the interfaces it exposes. This would be that.

The main disadvantage that I see is that it increases the complexity of where doc comments can be, and potentially conflicts with a doc comment of the first thing in a file.

Added complexity is a judgement call. It's never good on its own, but I think the benefits of well-documented code outweigh the cognitive load imposed by the extra rules: "The doc comment documents whatever immediately follows it. Or, if the doc comment is at the start of a file, it documents the whole file." If the alternative is that I can't explain to a user of my library how best to compose its parts outside the descriptions of those parts, I think it's worth it.

As for conflicting, the first thing in a Zig source file I write is almost always const std = @import("std"); which isn't pub and, if it does need documentation, a regular comment would suffice. In the rare cases where a file does begin with an exported symbol, I think a blank line after the module-level comment is intuitive enough.

/// Module-level doc comment, explain what this library is and how
/// it's intended to be used.

/// First function in module, accepts bases and returns true iff they are
/// all belong to us.
pub fn belongToUs(allYourBase: []Base) bool {

An extra decision to make is what to do in this situation:

/// Doc comment as the first line in a file
const std = @import("std");

I see three options:

1. The compiler could complain that there's an ambiguous doc comment.
2. The doc comment could be assigned to the module.
3. The doc comment could be assigned to the symbol (std).

I favor 1, since a compiler's job is not to infer intent when it's unclear. However, there's a case to be made for 2, since it's almost definitely what the user intended.

[deingithub]

There's already a top-level doc comment syntax with //!, see #2288 :)

[nmichaels]

Well that's good for me. If only it were documented...