Fix up documentation around no_std

src/doc/book/no-stdlib.md

@@ -21,7 +21,7 @@ this using our `Cargo.toml` file:
 
 ```toml
 [dependencies]
-libc = { version = "0.2.11", default-features = false }
+libc = { version = "0.2.14", default-features = false }
 ```
 
 Note that the default features have been disabled. This is a critical step -
@@ -36,8 +36,7 @@ or overriding the default shim for the C `main` function with your own.
 The function marked `#[start]` is passed the command line parameters
 in the same format as C:
 
-```rust
-# #![feature(libc)]
+```rust,ignore
 #![feature(lang_items)]
 #![feature(start)]
 #![no_std]
@@ -51,53 +50,77 @@ fn start(_argc: isize, _argv: *const *const u8) -> isize {
     0
 }
 
-// These functions and traits are used by the compiler, but not
+// These functions are used by the compiler, but not
 // for a bare-bones hello world. These are normally
 // provided by libstd.
-#[lang = "eh_personality"] extern fn eh_personality() {}
-#[lang = "panic_fmt"] extern fn panic_fmt() -> ! { loop {} }
-# #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
-# #[no_mangle] pub extern fn rust_eh_register_frames () {}
-# #[no_mangle] pub extern fn rust_eh_unregister_frames () {}
-# // fn main() {} tricked you, rustdoc!
+#[lang = "eh_personality"]
+#[no_mangle]
+pub extern fn eh_personality() {
+}
+
+#[lang = "panic_fmt"]
+#[no_mangle]
+pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
+                               _file: &'static str,
+                               _line: u32) -> ! {
+    loop {}
+}
 ```
 
 To override the compiler-inserted `main` shim, one has to disable it
 with `#![no_main]` and then create the appropriate symbol with the
 correct ABI and the correct name, which requires overriding the
 compiler's name mangling too:
 
-```rust
-# #![feature(libc)]
+```rust,ignore
 #![feature(lang_items)]
 #![feature(start)]
 #![no_std]
 #![no_main]
 
+// Pull in the system libc library for what crt0.o likely requires
 extern crate libc;
 
+// Entry point for this program
 #[no_mangle] // ensure that this symbol is called `main` in the output
-pub extern fn main(argc: i32, argv: *const *const u8) -> i32 {
+pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 {
     0
 }
 
-#[lang = "eh_personality"] extern fn eh_personality() {}
-#[lang = "panic_fmt"] extern fn panic_fmt() -> ! { loop {} }
-# #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
-# #[no_mangle] pub extern fn rust_eh_register_frames () {}
-# #[no_mangle] pub extern fn rust_eh_unregister_frames () {}
-# // fn main() {} tricked you, rustdoc!
+// These functions and traits are used by the compiler, but not
+// for a bare-bones hello world. These are normally
+// provided by libstd.
+#[lang = "eh_personality"]
+#[no_mangle]
+pub extern fn eh_personality() {
+}
+
+#[lang = "panic_fmt"]
+#[no_mangle]
+pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
+                               _file: &'static str,
+                               _line: u32) -> ! {
+    loop {}
+}
 ```
 
-The compiler currently makes a few assumptions about symbols which are available
-in the executable to call. Normally these functions are provided by the standard
-library, but without it you must define your own.
+## More about the langauge items
+
+The compiler currently makes a few assumptions about symbols which are
+available in the executable to call. Normally these functions are provided by
+the standard library, but without it you must define your own. These symbols
+are called "language items", and they each have an internal name, and then a
+signature that an implementation must conform to.
 
 The first of these two functions, `eh_personality`, is used by the failure
 mechanisms of the compiler. This is often mapped to GCC's personality function
 (see the [libstd implementation][unwind] for more information), but crates
 which do not trigger a panic can be assured that this function is never
-called. The second function, `panic_fmt`, is also used by the failure
-mechanisms of the compiler.
-
+called. Both the language item and the symbol name are `eh_personality`.
+
 [unwind]: https://github.com/rust-lang/rust/blob/master/src/libpanic_unwind/gcc.rs
+
+The second function, `panic_fmt`, is also used by the failure mechanisms of the
+compiler. When a panic happens, this controls the message that's displayed on
+the screen. While the language item's name is `panic_fmt`, the symbol name is
+`rust_begin_panic`.

src/libcore/lib.rs

@@ -25,6 +25,8 @@
 //!
 //! # How to use the core library
 //!
+//! Please note that all of these details are currently not considered stable.
+//!
 // FIXME: Fill me in with more detail when the interface settles
 //! This library is built on the assumption of a few existing symbols:
 //!
@@ -34,11 +36,12 @@
 //!   These functions are often provided by the system libc, but can also be
 //!   provided by the [rlibc crate](https://crates.io/crates/rlibc).
 //!
-//! * `rust_begin_unwind` - This function takes three arguments, a
-//!   `fmt::Arguments`, a `&str`, and a `u32`. These three arguments dictate
-//!   the panic message, the file at which panic was invoked, and the line.
-//!   It is up to consumers of this core library to define this panic
-//!   function; it is only required to never return.
+//! * `rust_begin_panic` - This function takes three arguments, a
+//!   `fmt::Arguments`, a `&'static str`, and a `u32`. These three arguments
+//!   dictate the panic message, the file at which panic was invoked, and the
+//!   line. It is up to consumers of this core library to define this panic
+//!   function; it is only required to never return. This requires a `lang`
+//!   attribute named `panic_fmt`.
 
 // Since libcore defines many fundamental lang items, all tests live in a
 // separate crate, libcoretest, to avoid bizarre issues.