From dbeea18fc5f94d29db74144e55089cc55aa8e11d Mon Sep 17 00:00:00 2001
From: Tim Chevalier <chevalier@alum.wellesley.edu>
Date: Mon, 1 Apr 2013 14:04:32 -0700
Subject: [PATCH 1/2] docs: Document language items, as per #3342

---
 doc/rust.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 99 insertions(+), 1 deletion(-)

diff --git a/doc/rust.md b/doc/rust.md
index 24200459d90..fef894792be 100644
--- a/doc/rust.md
+++ b/doc/rust.md
@@ -1420,13 +1420,111 @@ names are effectively reserved. Some significant attributes include:
 
 * The `doc` attribute, for documenting code in-place.
 * The `cfg` attribute, for conditional-compilation by build-configuration.
+* The `lang` attribute, for custom definitions of traits and functions that are known to the Rust compiler (see [Language items](#language-items)).
 * The `link` attribute, for describing linkage metadata for a crate.
 * The `test` attribute, for marking functions as unit tests.
-* The `allow`, `warn`, `forbid`, and `deny` attributes, for controling lint checks. Lint checks supported
+* The `allow`, `warn`, `forbid`, and `deny` attributes, for controlling lint checks. Lint checks supported
 by the compiler can be found via `rustc -W help`.
 
 Other attributes may be added or removed during development of the language.
 
+### Language items
+
+Some primitive Rust operations are defined in Rust code,
+rather than being implemented directly in C or assembly language.
+The definitions of these operations have to be easy for the compiler to find.
+The `lang` attribute makes it possible to declare these operations.
+For example, the `str` module in the Rust core library defines the string equality function:
+
+~~~
+#[lang="str_eq"]
+pub fn eq_slice(a: &str, b: &str) -> bool {
+    true // not actually the implementation
+}
+~~~
+
+The name `str_eq` has a special meaning to the Rust compiler,
+and the presence of this definition means that it will use this definition
+when generating calls to the string equality function.
+
+A complete list of the built-in language items follows:
+
+#### Traits
+
+`const`
+  : Cannot be mutated.
+`copy`
+  : Can be implicitly copied.
+`owned`
+  : Are uniquely owned.
+`durable`
+  : Contain borrowed pointers.
+`drop`
+  : Have finalizers.
+`add`
+  : Elements can be added (for example, integers and floats).
+`sub`
+  : Elements can be subtracted.
+`mul`
+  : Elements can be multiplied.
+`div`
+  : Elements can be divided.
+`mod`
+  : Elements have a modulo operation.
+`neg`
+  : Elements can be negated arithmetically.
+`not`
+  : Elements can be negated logically.
+`bitxor`
+  : Elements have an exclusive-or operation.
+`bitand`
+  : Elements have a bitwise `and` operation.
+`bitor`
+  : Elements have a bitwise `or` operation.
+`shl`
+  : Elements have a left shift operation.
+`shr`
+  : Elements have a right shift operation.
+`index`
+  : Elements can be indexed.
+`eq`
+  : Elements can be compared for equality.
+`ord`
+  : Elements have a partial ordering.
+
+#### Operations
+
+`str_eq`
+  : Compare two strings for equality.
+`uniq_str_eq`
+  : Compare two owned strings for equality.
+`annihilate`
+  : Destroy a box before freeing it.
+`log_type`
+  : Generically print a string representation of any type.
+`fail_`
+  : Abort the program with an error.
+`fail_bounds_check`
+  : Abort the program with a bounds check error.
+`exchange_malloc`
+  : Allocate memory on the exchange heap.
+`exchange_free`
+  : Free memory that was allocated on the exchange heap.
+`malloc`
+  : Allocate memory on the managed heap.
+`free`
+  : Free memory that was allocated on the managed heap.
+`borrow_as_imm`
+  : Create an immutable borrowed pointer to a mutable value.
+`return_to_mut`
+  : Release a borrowed pointer created with `return_to_mut`
+`check_not_borrowed`
+  : Fail if a value has existing borrowed pointers to it.
+`strdup_uniq`
+  : Return a new unique string containing a copy of the contents of a unique string.
+
+> **Note:** This list is likely to become out of date. We should auto-generate it
+> from `librustc/middle/lang_items.rs`.
 
 # Statements and expressions
 

From ce096455918920012c4fb3dcd48b1688e571b759 Mon Sep 17 00:00:00 2001
From: Tim Chevalier <chevalier@alum.wellesley.edu>
Date: Mon, 1 Apr 2013 15:21:22 -0700
Subject: [PATCH 2/2] docs: Xfail test, it's just for illustration anyway

---
 doc/rust.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/rust.md b/doc/rust.md
index fef894792be..c6dba962676 100644
--- a/doc/rust.md
+++ b/doc/rust.md
@@ -1436,10 +1436,10 @@ The definitions of these operations have to be easy for the compiler to find.
 The `lang` attribute makes it possible to declare these operations.
 For example, the `str` module in the Rust core library defines the string equality function:
 
-~~~
+~~~ {.xfail-test}
 #[lang="str_eq"]
 pub fn eq_slice(a: &str, b: &str) -> bool {
-    true // not actually the implementation
+    // details elided
 }
 ~~~