Document standard library organization

[marler8997]

Even though I've used the standard library a fair amount, I'm still unsure of where to find things when I need them and where to add things when I make contributions. I've searched for a document that describes where things go but haven't found one, and I've also encountered differences in opinion about where things are meant to go.

I'd like to see documentation that explains the purpose for each module in the standard library. Things like:

• std.c: external symbol declarations for libc
• std.os.windows.bits: constant/struct type declarations used throughout the windows API
• std.os.windows: wraps the windows APIs to make them more zig friendly
• std.os.windows.kernel32: external symbol declarations for kernel32.dll
• std.fs.file: platform-independent API for managing files

Since this information changes, it's probably best to put it somewhere inside the zig repository. Maybe it should be put in std.zig as apart of the documentation comments that are rendered into the standard library docs.

[nmichaels]

I think the best place to put this kind of documentation is in top-level doc comments (#2288). Each file can document its purpose, and the doc generation process can compile a list.

[nmichaels]

Alternatively, doc comments in std.zig for each exported symbol would also get us something good, though it's not quite as connected to the content.

[marler8997]

I realized today we have top-level doc comments:

//! this modules does X

So it looks like this issue can be solved by just going through modules in the standard library and adding top-level doc comments.

Executive Summary?

One thought I had is it could be nice to have an executive summary of all the modules in a single place so users can find what they need without needing to open/search through every file/module. We could do this by using a convention that each module include a short summary of what it contains in the first line of its top-level comment and pull this summary from each module during doc generation. This is the same convention git uses for the commit messages (1st line is a summary). So it would look something like this.

std/c.zig

//! external symbol declarations for libc
//!
//! more documentatation for this module...

std/os/bits.zig

//! platform-dependent types and values used for os-specific APIs
//!
//! more documentatation for this module...

The executive summary would include a list of all the modules and the first-line of their top-level doc comment:

• std/c.zig: external symbol declarations for libc
• std/os/bits.zig: platform-dependent types and values used for os-specific APIs
• ...