---

yaml
---
r: 161082
b: refs/heads/try
c: 0b6ec70
h: refs/heads/master
v: v3

Author: nikomatsakis

[refs]

@@ -2,7 +2,7 @@
 refs/heads/master: 4eb72d268f337a8f117c86a2ac1b98336cab9e9d
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: c9f6d696420107f82304b992cf623b806995fe18
-refs/heads/try: cbdaf2ebc7d39588a5f6efee1cd9de0a273571a9
+refs/heads/try: 0b6ec701974096b68e666693b8a750fb6a5d65c6
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596

branches/try/configure

@@ -1031,7 +1031,6 @@ do
     make_dir $h/test/doc-guide-tasks
     make_dir $h/test/doc-guide-plugin
     make_dir $h/test/doc-guide-crates
-    make_dir $h/test/doc-guide-error-handling
     make_dir $h/test/doc-rust
 done
 

branches/try/mk/docs.mk

@@ -27,7 +27,7 @@
 ######################################################################
 DOCS := index intro tutorial guide guide-ffi guide-macros guide-lifetimes \
 	guide-tasks guide-container guide-pointers guide-testing \
-	guide-plugin guide-crates complement-bugreport guide-error-handling \
+	guide-plugin guide-crates complement-bugreport \
 	complement-lang-faq complement-design-faq complement-project-faq \
     rustdoc guide-unsafe guide-strings reference
 

branches/try/src/doc/guide-error-handling.md

@@ -59,7 +59,6 @@ a guide that can help you out:
 * [References and Lifetimes](guide-lifetimes.html)
 * [Crates and modules](guide-crates.html)
 * [Tasks and Communication](guide-tasks.html)
-* [Error Handling](guide-error-handling.html)
 * [Foreign Function Interface](guide-ffi.html)
 * [Writing Unsafe and Low-Level Code](guide-unsafe.html)
 * [Macros](guide-macros.html)

branches/try/src/doc/index.md

@@ -20,7 +20,6 @@
 [type: text] src/doc/guide-testing.md $lang:doc/l10n/$lang/guide-testing.md
 [type: text] src/doc/guide-unsafe.md $lang:doc/l10n/$lang/guide-unsafe.md
 [type: text] src/doc/guide-crates.md $lang:doc/l10n/$lang/guide-crates.md
-[type: text] src/doc/guide-error-handling.md $lang:doc/l10n/$lang/guide-error-handling.md
 [type: text] src/doc/guide.md $lang:doc/l10n/$lang/guide.md
 [type: text] src/doc/index.md $lang:doc/l10n/$lang/index.md
 [type: text] src/doc/intro.md $lang:doc/l10n/$lang/intro.md

branches/try/src/doc/po4a.conf

@@ -3557,14 +3557,17 @@ The machine types are the following:
 
 #### Machine-dependent integer types
 
-The `uint` type is an unsigned integer type with the same number of bits as the
-platform's pointer type. It can represent every memory address in the process.
-
-The `int` type is a signed integer type with the same number of bits as the
-platform's pointer type. The theoretical upper bound on object and array size
-is the maximum `int` value. This ensures that `int` can be used to calculate
-differences between pointers into an object or array and can address every byte
-within an object along with one byte past the end.
+The Rust type `uint` [^rustuint] is an
+unsigned integer type with target-machine-dependent size. Its size, in
+bits, is equal to the number of bits required to hold any memory address on
+the target machine.
+
+The Rust type `int` [^rustint]  is a two's complement signed integer type with
+target-machine-dependent size. Its size, in bits, is equal to the size of the
+rust type `uint` on the same target machine.
+
+[^rustuint]: A Rust `uint` is analogous to a C99 `uintptr_t`.
+[^rustint]: A Rust `int` is analogous to a C99 `intptr_t`.
 
 ### Textual types
 

branches/try/src/doc/reference.md

@@ -227,6 +227,52 @@
 //! ```
 //!
 //! `try!` is imported by the prelude, and is available everywhere.
+//!
+//! # `Result` and `Option`
+//!
+//! The `Result` and [`Option`](../option/index.html) types are
+//! similar and complementary: they are often employed to indicate a
+//! lack of a return value; and they are trivially converted between
+//! each other, so `Result`s are often handled by first converting to
+//! `Option` with the [`ok`](type.Result.html#method.ok) and
+//! [`err`](type.Result.html#method.ok) methods.
+//!
+//! Whereas `Option` only indicates the lack of a value, `Result` is
+//! specifically for error reporting, and carries with it an error
+//! value.  Sometimes `Option` is used for indicating errors, but this
+//! is only for simple cases and is generally discouraged. Even when
+//! there is no useful error value to return, prefer `Result<T, ()>`.
+//!
+//! Converting to an `Option` with `ok()` to handle an error:
+//!
+//! ```
+//! use std::io::Timer;
+//! let mut t = Timer::new().ok().expect("failed to create timer!");
+//! ```
+//!
+//! # `Result` vs. `panic!`
+//!
+//! `Result` is for recoverable errors; `panic!` is for unrecoverable
+//! errors. Callers should always be able to avoid panics if they
+//! take the proper precautions, for example, calling `is_some()`
+//! on an `Option` type before calling `unwrap`.
+//!
+//! The suitability of `panic!` as an error handling mechanism is
+//! limited by Rust's lack of any way to "catch" and resume execution
+//! from a thrown exception. Therefore using panics for error
+//! handling requires encapsulating code that may panic in a task.
+//! Calling the `panic!` macro, or invoking `panic!` indirectly should be
+//! avoided as an error reporting strategy. Panics is only for
+//! unrecoverable errors and a panicking task is typically the sign of
+//! a bug.
+//!
+//! A module that instead returns `Results` is alerting the caller
+//! that failure is possible, and providing precise control over how
+//! it is handled.
+//!
+//! Furthermore, panics may not be recoverable at all, depending on
+//! the context. The caller of `panic!` should assume that execution
+//! will not resume after the panic, that a panic is catastrophic.
 
 #![stable]