langref: improve atomics documentation #16483
Conversation
There was a problem hiding this comment.
Opinion: we probably shouldn't try documenting AtomicOrder until the memory model is documented. There's a few edge cases we'd have to note in addition to what's covered. If not, incorrect invariants could be inferred like "observing normal store A with Acquire, which happened after Release store B, means you get the Acq<->Rel visibility of B" (this is false AFAIK)
Fair enough. I removed the docs for now. |
|
Not that I have any standing in Zig to bless this change, but the doc changes here look good to me. Moving the standard library doc into the standard library itself seems like the right direction to go in, and the textual change looks legit to me. The other cleanups to langref in here look good too. |
|
Yup, and I also just resolved the conflicts that I noticed thanks to your comment @rootbeer. So if anyone is interested in merging this... |
The explanations for the packages weren't on a separate line. This also adds an explanation for the "std" package.
This does a few things.
* This moves some documentation into `lib/std/builtin.zig` where it belongs
* Resolves inconsistencies in parameter types.
Sometimes it was `@import("std").builtin.X`, sometimes `std.builtin.X`, sometimes `builtin.X`, or just `X`.
Now I changed it all to `std.builtin.X` because it's a good balance
between not being too long (especially for some of the atomics builtins) while not being ambiguous
(the `builtin` in `builtin.X` might be mistaken as `@import("builtin")` instead of `std.builtin`).
* No longer copy-pastes `PrefetchOptions` into the langref.
I think this is just a bad idea long-term. It will get out of date
over and over and also if we're copy-pasting `PrefetchOptions` why
aren't we doing that for other structs? That's inconsistent.
The user should know to reference the standard library documentation
if they want to know what a struct that is used in a builtin's prototype does.
We shouldn't mix std documentation and language documentation.
* moves some langref into std.builtin doc comments * use the same way of referencing stuff from std.builtin closes ziglang#16483
This does a few things.
lib/std/builtin.zigwhere it belongs.Sometimes it was
@import("std").builtin.X, sometimesstd.builtin.X, sometimesbuiltin.X, or justX.Now I changed it all to
std.builtin.Xbecause it's a good balancebetween not being too long (especially for some of the atomics builtins) while not being ambiguous
(the
builtininbuiltin.Xmight be mistaken as@import("builtin")instead ofstd.builtin).PrefetchOptionsinto the langref.I think this is just a bad idea long-term. It will get out of date
over and over and also if we're copy-pasting
PrefetchOptionswhyaren't we doing that for other structs? That's inconsistent.
The user should know to reference the standard library documentation
if they want to know what an std struct that is used in a builtin's prototype does.
We shouldn't mix std documentation and language documentation.