That sounds rather like a different thing was wrong - not where the author tried to lean: Zig has crap documentation.
Zig is young. They're spending their time maturing the core ecosystem --- the compiler, the standard library, and so forth. It's perfectly reasonable to expect early adopters to "RTFS/read the fucking source". *When* they start writing documentation, I'd be perfectly happy to hear comments like "The zig documentation is crap".
At this stage of the project, I'll be honest, I find it upsetting to read comments like this.
Right now, Zig is young and the documentation is kinda ok (Language reference is clear enough, outside a few things that need better visibility, for example, explaining concepts that are only on the examples can be lost easy), the autogenerated std on the other hand used to work meh, until a commit broke it afaik, so rn is in a pityfull state, but there is no use in reworking it until stage 2, so that's that
Well, crap as an offering (what you get atm), not necessarily as in the quality of what little it is. It does though have a reference and documentation page:
These docs are experimental. Progress depends on the self-hosted compiler, consider reading the stdlib source in the meantime.
For auditing you are right, of course.
I mean, as a first note one of the ideas here is reading code already written in zig to understand how to write code in zig - so in that case you're effectively inferring the interface from what the authors of the code itself are treating said interface to be.
But also, interface documentation is pretty much never truly complete because there are almost always some implicit assumptions involved (and if you try and make all of those explicit you rapidly end up with documentation that's so verbose people's eyes glaze over when they try to read it so their model often ends up incomplete anyway so how explicit to be is itself a trade-off).
Then zig embeds its test cases in the source file, so you can look at what the authors have explicitly declared -must- work to help you know what the interface is intended to be.
Plus when I'm source diving, I've done enough of it over the years to be able to at least attempt to build up a model of not just the implementation, but of the author's mental model as they were implementing it, and if you can figure out their intent, it's much easier to guess what their code is -meant- to do and thereby what it will hopefully continue to do into the future.
If in doubt, though, leaving a comment in your own code as to what assumption you're making -and- writing a unit test in your own code that verifies the assumption continues to hold will mean that at least if it doesn't you'll see a test failure in your own suite that tells you it changed.
(or: "code to the interface, not the implementation" is absolutely the right thing to aim for, but in practice the line between the two is fuzzy and cases where you have to make a judgement call will always show up eventually)