top-level doc comment should be allowed in zig fmt

[tiehuis]

Take the following program:

/// Top-level documentation.

/// This is A
pub const A = usize;

After applying zig fmt this is turned into:

/// Top-level documentation.
/// This is A
pub const A = usize;

I don't think we should collapse top-level documentation at the beginning of the ast. I note that we have Error.UnattachedDocComment in zig/ast.zig. I do think it still makes sense to emit an error for documentation which isn't attached in the middle of a file, as I'm not sure how it could be interpreted in a meaningful way.

Related, but running zig fmt on a file with only a doc comment deletes it.

[tiehuis]

This assumes we want top-level documentation. There may be alternatives that are better suited and we can play with more once the documentation generator is started.

For example, since a file is semantically a struct (by #1047), would we also allow this sort of top-level documentation as allowed as the first node in a struct ast. It may be better to handle these differently even if semantically they are the same, so have the least surprising behaviour.

[Vexu]

Are top level doc comments something we want now that documentation generation is here?

For normal containers and namespaces the need for top level doc comments can easily be avoided. However we'll probably need them if we want to document a package in its root file.

[Vexu]

If we want container level doc comments we should probably copy rust and have a different kind of comment for them since properly parsing

/// container doc comment

/// declaration doc comment
const A = ...

requires the parser to understand whitespace whereas

//! container doc comment

/// declaration doc comment
const A = ...

doesn't.

[andrewrk]

I agree with copying rust here. It's unfortunate that there will be 2 ways to add doc comments for a container which is not the file, but maybe zig fmt can canonicalize that.