doc: describe the Drop trait. cc: rust-lang#4217

graydon · graydon · commit 66aadecfee10 · 2012-12-20T16:26:11.000-08:00
diff --git a/doc/rust.md b/doc/rust.md
@@ -2845,6 +2845,16 @@ The kinds are:
     sendable kind are copyable, as are managed boxes, managed closures,
     trait types, and structural types built out of these.
     Types with destructors (types that implement `Drop`) can not implement `Copy`.
+`Drop`
+  : This is not strictly a kind, but its presence interacts with kinds: the `Drop`
+    trait provides a single method `finalize` that takes no parameters, and is run
+    when values of the type are dropped. Such a method is called a "destructor",
+    and are always executed in "top-down" order: a value is completely destroyed
+    before any of the values it owns run their destructors. Only `Owned` types
+    that do not implement `Copy` can implement `Drop`.
+
+> **Note:** The `finalize` method may be renamed in future versions of Rust.
+
 _Default_
   : Types with destructors, closure environments,
     and various other _non-first-class_ types,
