It’s widely acknowledged that the stdlib docs leave something to be desired and/or might even be doing more harm than good. Particularity since the stdlib code itself is regarded as very readable and well commented.
On the other hand, handing people a link to ziglang/zig/tree/master/lib/std and saying, “have fun and come home when it gets dark,” isn’t great either.
This got me to thinking about a halfway solution: A human-written “table of contents” of stdlib functionality with a one-sentence descriptions of each type/value/function and a link to the source location for further perusal. Ideally the table of contents would also briefly explain the purpose of each namespace as well as some general tips about which functions to use for which purpose.
The idea would be to give people a starting place for understanding the organization and purpose of the library while still encouraging them to go read the source for more information.
(Note: If this sounds similar to what we currently have with the auto-generated documentation, I didn’t explain it well enough.)
I’m curious what everyone thinks of this idea or if anyone can think of other “light effort” alternatives to “proper” documentation?