autodoc: top-level file doc-comment is not rendered from files in the crypto namespace

[perillo]

Zig Version

0.13.0-dev.44+9d64332a5

Steps to Reproduce and Observed Behavior

I found this issue while reading 8a36a1f and running zig std. The file documentation is not added.

This issue is probably caused by the fact that in the crypto namespace, files are imported from inside a struct.

Another problem with how zig std is structured is that often important top-level file documentation is ignored, because only some declarations are imported, instead of the file.

An example is std/crypto/aegis.zig.

Expected Behavior

The top-level file doc-comment should always be available in the docs, since it may contain useful information.

[ianprime0509]

Due to the way Autodoc resolves paths, this file-level documentation is actually still available to view (e.g. see #std.crypto.aegis). However, as you noted, since aegis.zig is never actually exposed as a namespace of its own and only selectively imported from, the namespace isn't listed when browsing the #std.crypto docs directly.

One of the items from #19249 is "in source view, make @imports into links, but keep same syntax highlighting", which I think would help with this somewhat, by allowing users to see the @import("crypto/aegis.zig") in the source code and click it to get more information.

Another way Autodoc makes this discoverable is in how it handles the breadcrumb navigation for each decl: if you click through to #std.crypto.aead.aegis and click one of the types on that page, it actually resolves to a path like #std.crypto.aegis.Aegis128L, where clicking on aegis in the navigation leads back to #std.crypto.aegis with the file documentation available.