@@ -1324,10 +1324,8 @@ impl<T> Weak<T> {
13241324
13251325 /// Returns a raw pointer to the object `T` pointed to by this `Weak<T>`.
13261326 ///
1327- /// It is up to the caller to ensure that the object is still alive when accessing it through
1328- /// the pointer.
1329- ///
1330- /// The pointer may be [`null`] or be dangling in case the object has already been destroyed.
1327+ /// The pointer is valid only if there are some strong references. The pointer may be dangling
1328+ /// or even [`null`] otherwise.
13311329 ///
13321330 /// # Examples
13331331 ///
@@ -1408,14 +1406,18 @@ impl<T> Weak<T> {
14081406 /// This can be used to safely get a strong reference (by calling [`upgrade`]
14091407 /// later) or to deallocate the weak count by dropping the `Weak<T>`.
14101408 ///
1411- /// It takes ownership of one weak count. In case a [`null`] is passed, a dangling [`Weak`] is
1412- /// returned .
1409+ /// It takes ownership of one weak count (with the exception of pointers created by [`new`],
1410+ /// as these don't have any corresponding weak count) .
14131411 ///
14141412 /// # Safety
14151413 ///
1416- /// The pointer must represent one valid weak count. In other words, it must point to `T` which
1417- /// is or *was* managed by an [`Arc`] and the weak count of that [`Arc`] must not have reached
1418- /// 0. It is allowed for the strong count to be 0.
1414+ /// The pointer must have originated from the [`into_raw`] (or [`as_raw'], provided there was
1415+ /// a corresponding [`forget`] on the `Weak<T>`) and must still own its potential weak reference
1416+ /// count.
1417+ ///
1418+ /// It is allowed for the strong count to be 0 at the time of calling this, but the weak count
1419+ /// must be non-zero or the pointer must have originated from a dangling `Weak<T>` (one created
1420+ /// by [`new`]).
14191421 ///
14201422 /// # Examples
14211423 ///
@@ -1440,11 +1442,13 @@ impl<T> Weak<T> {
14401442 /// assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none());
14411443 /// ```
14421444 ///
1443- /// [`null`]: ../../std/ptr/fn.null.html
1445+ /// [`as_raw`]: struct.Weak.html#method.as_raw
1446+ /// [`new`]: struct.Weak.html#method.new
14441447 /// [`into_raw`]: struct.Weak.html#method.into_raw
14451448 /// [`upgrade`]: struct.Weak.html#method.upgrade
14461449 /// [`Weak`]: struct.Weak.html
14471450 /// [`Arc`]: struct.Arc.html
1451+ /// [`forget`]: ../../std/mem/fn.forget.html
14481452 #[ unstable( feature = "weak_into_raw" , issue = "60728" ) ]
14491453 pub unsafe fn from_raw ( ptr : * const T ) -> Self {
14501454 if ptr. is_null ( ) {
0 commit comments