OnceCell docs: empty/full terminology v.s. (un)initialized

[SimonSapin]

Documentation at:

• https://doc.rust-lang.org/nightly/std/lazy/struct.OnceCell.html
• https://doc.rust-lang.org/nightly/std/lazy/struct.SyncOnceCell.html

Appears to use "empty" and "uninitialized" interchangeably to describe the state of a given cell, and similarly "full" and "initialized". I think it’d be better to pick one set of terminology and stick to it consistently. Using empty/full might be better because "uninitialized" terminology is already used for std::mem::MaybeUninit, and manipulating an empty cell does not have the memory-safety risks of reading bytes from MaybeUninit::uninit().

[camsteffen]

"initialized" corresponds with the API methods like get_or_init. I think that particular consistency is more important.

[Cyborus04]

What about get_or or get_or_with instead?

[hkBst]

Given links are dangling, but I think this is about:

• https://doc.rust-lang.org/nightly/std/cell/struct.OnceCell.html
• https://doc.rust-lang.org/nightly/std/sync/struct.OnceLock.html

I believe the states should be called empty and initialized, with the transition being initializing.
Thus:

• uninitialized should be replaced by empty
• full should be replaced by initialized

[hkBst]

@rustbot labels: +E-easy

[Pyr0de]

I believe the states should be called empty and initialized, with the transition being initializing. Thus:

* uninitialized should be replaced by empty

* full should be replaced by initialized

Hey,
If this is terminology that is preferred, I could make the changes.

@rustbot claim

[hkBst]

@Pyr0de it's just my informed opinion, and what I would do (you may find out when your PR gets reviewed that other people disagree or not). BTW I think "full" should be replaced by something like "already initialized". Anyway use your best judgment! Good luck.

[Pyr0de]

pub fn set(&self, value: T) -> Result<(), T>

Sets the contents of the cell to value.

Hey,
Since OnceCell already has functions like set and it also uses "sets" in its docs, I could replace

• "empty" with "unset" / "not set"
• "initialized" with "set"

Example: "Creates a new unset cell"

Or does this change the meaning?

[hkBst]

@Pyr0de I think that would also be fine.

[Pyr0de]

Should I also change the comments to match the changes or just the docs?

[hkBst]

@Pyr0de if you are talking about comments in code examples, then yes change those to match as well.

[Pyr0de]

I did make the changes in the code example comments.
I was wondering if I had to make changes in the code comments left for explaining the code, not part of the docs

[hkBst]

@Pyr0de I'm not sure what you mean by "code comments left for explaining the code, not part of the docs". Ah do you mean like ordinary non-doc comments? Ideally yes.