std::sync::OnceState: Confusing documentation for poisoned method

[joshlf]

The documentation for std::sync::OnceState::poisoned reads:

Returns whether the associated Once has been poisoned.

Once an initalization routine for a Once has panicked it will forever indicate to future forced initialization routines that it is poisoned.

This is confusing because it implies that calls to call_once_force can execute multiple times, but of course the whole point of a Once is that calls only execute once. Even call_once_force only executes so long as the Once is poisoned - as soon as it is in the COMPLETE state, call_once_force calls become no-ops.

A better wording might be:

Once an initialization routine for a Once has panicked, it will forever indicate to future forced initialization routines that it is poisoned. Of course, once a single forced initialization routine successfully completes, the Once will no longer be poisoned, but no future initialization routes will be run either.

[frewsxcv]

i opened a pull request for this: #45429