Autodoc: only group structs under "namespaces"

[ianprime0509]

The old heuristic of checking only for the number of fields has the downside of classifying all opaque types, such as std.c.FILE, as "namespaces" rather than "types".

Before:

After:

[rohlem]

I personally exclusively use opaque for declaration containers, because instantiating them isn't sensible, and opaque forbids direct instantiations.
From what I understand this new heuristic implies that opaque types never count as namespaces anymore,
instead encouraging users to use struct for namespaces even if instantiating them isn't meaningful/sensible.
Is there a reason we want to encourage this stylistically?

Then again, I don't have a better heuristic to offer; the actual criterion for whether opaque is used as a type is whether T is ever used as a pointee in *T or not.
Technically we only know this to be false for uninstantiable types, meaning all namespaces should really be stateless enum-s or union-s.
I think the cleanest solution would be to re-introduce a namespace type (previously only available via file-scopes before #1047),
but having such a type just for documentation purposes might be considered not useful enough to model it in the language.

[ianprime0509]

@rohlem Yes, that's correct: with this change, only structs will be eligible to be classified as "namespaces" on their parent container's page.

My main argument in favor of treating struct as the default "namespace container" is that that's what you get when you use a separate file for grouping declarations. It's true that it's nonsensical to instantiate a struct that's only supposed to be used as a namespace, but that's already possible for all existing namespaces which are created using files (e.g. const s: std = .{} is technically legal).

Additionally, this seems to be the dominant style at least within the current compiler and standard library code: as a first approximation, if we assume that namespace names are snake_case (following the style guide), then the following regexes can be used to find examples:

• const [a-z]\w* = struct \{ - many examples, such as https://github.com/ziglang/zig/blob/bf588f67d8c6261105f81fd468c420d662541d2a/lib/std/crypto.zig
• const [a-z]\w* = opaque \{ - only three matches found (outside test cases), all of which are actually types:

  lib/std/os/emscripten.zig:pub const struct__em_promise = opaque {};
  lib/std/c/darwin.zig:pub const os_log_t = opaque {};
  lib/std/c/openbsd.zig:pub const auth_session_t = opaque {};
  

[andrewrk]

Nice, thanks!