Change:
/// This can be used to safely get a strong reference (by calling [`upgrade`] /// later) or to deallocate the weak count by dropping the `Weak<T>`. /// <del> /// It takes ownership of one weak count (with the exception of pointers created by [`new`], /// as these don't have any corresponding weak count). </del> <ins> /// It takes ownership of one weak reference (with the exception of pointers created by [`new`], /// as these don't own anything; the method still works on them). </ins> /// /// # Safety /// <del> /// The pointer must have originated from the [`into_raw`]  and must still own its potential /// weak reference count. </del> <ins> /// The pointer must have originated from the [`into_raw`] and must still own its potential /// weak reference. </ins> /// <del> /// It is allowed for the strong count to be 0 at the time of calling this, but the weak count /// must be non-zero or the pointer must have originated from a dangling `Weak<T>` (one created /// by [`new`]). </del> <ins> /// It is allowed for the strong count to be 0 at the time of calling this. Nevertheless, this /// takes ownership of one weak reference currently represented as a raw pointer (the weak /// count is not modified by this operation) and therefore it must be paired with a previous /// call to [`into_raw`]. </ins> /// /// # Examples ///

Discussion:
... as documented. The problem: this line from the documentation: The weak count as reported by is 0 when the strong count is 0, even if there are still outstanding weak references: The combination of these two means that getting a pointer from is not enough to guarantee that it's safe to use in . Instead, you have to know that (if it originated from a strong reference) you still have an outstanding strong reference to the allocation, because otherwise the (exposed) weak count is 0, and thus calling is "documented UB". To properly document when this is intuitively allowed (i.e. it's allowed because I got the pointer from and have called more than , so there are still "unowned" raw weak references to claim) (which lines up with what the implementation allows), we need to expose (probably docs only) the fact that there is still being a weak reference count behind the hood being tracked until all of the s have been dropped. This will probably also require guaranteeing that doesn't drop its weak reference and become dangling "early" (e.g. note that failed, decrement the (real) weak count (potentially deallocating the place), and become a dangling weak via internal mutability) and that on a "zombie" increments the (real) weak count and creates a new "zombie" , not a dangling .
(I don't know if C-bug is the correct label for a "documentation bug," but it was the closest template to correct.)
I guess that means the internal weak count rather than the user-visible .
That's obviously the intent and what the implementation shows is the case, but when considering documented properties of an API, you have to only consider the documented API. A correct resolution to the issue would be to adjust the documentation to clarify that the weak count is referring to the hidden internal weak count that's not exposed (except conceptually for the safety of /). cc who wrote these methods and docs
Yes, it's meant as the actual number of weak pointers pointing there (including the ones „frozen“ to raw pointers), not what some method returns (if it's currently in the form of the raw pointer, you really can't even call the method, so I'm not sure if that part can even apply). I agree it could probably be documented better.

I'd try to fix the docs, but considering I've already updated them like 3 times during the review and they still haven't ended up entirely correct, I'll probably ask if you want to give it a go first, as obviously the docs aren't my strong ability :-).
The main thing this requires is actually specifying how the "internal" weak count works, and guarnateeing that we don't do "clever" things with converting "zombie "s into dangling s. I really don't know the best way to do this or even where to do this, since it basically only impacts how and when is allowed to be called.
:thinking: Maybe just getting rid of the „weak count“ term altogether and try to describe it in a way that the pointer preserves the ownership of the , or that it's an alternative form of and it can be turned back if it still has the ownership. Or maybe just point out that the „weak count“ is meant in its natural meaning, not referring to the method.
Ok, looking into this, how about wording like this? On the intoraw: And on the : Do you think this would be better?
Yeah, I think that wording captures the semantics properly.
Thanks. I'll get around to submitting the changes some time soonish.