Explain drop a bit more

Fixes #30655

1 files changed, 10 insertions, 0 deletions

diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs
index edbe64db080..1dc7a9ef2dc 100644
--- a/src/libcore/ops.rs
+++ b/src/libcore/ops.rs
@@ -95,6 +95,16 @@ use fmt;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Drop {
     /// A method called when the value goes out of scope.
+    ///
+    /// When this method has been called, `self` has not yet been deallocated.
+    /// If it were, `self` would be a dangling reference.
+    ///
+    /// After this function is over, the memory of `self` will be deallocated.
+    ///
+    /// # Panics
+    ///
+    /// Given that a `panic!` will call `drop()` as it unwinds, any `panic!` in
+    /// a `drop()` implementation will likely abort.
     #[stable(feature = "rust1", since = "1.0.0")]
     fn drop(&mut self);
 }