Documentation : Tutorial improvement...

Refactoring examples on implementation of generics for linked list.
Fixing typo of 'Note's for coherancy.

Adding internal links inside the tutorial example with traits,
generics etc...

1 files changed, 14 insertions, 5 deletions

diff --git a/src/doc/tutorial.md b/src/doc/tutorial.md
index 670ad5800c6..1c33d17ec66 100644
--- a/src/doc/tutorial.md
+++ b/src/doc/tutorial.md
@@ -133,6 +133,8 @@ fn main() {
     println!("hello?");
 }
 ~~~~
+> ***Note:*** *Macros* are explained in the [Syntax extensions
+> (3.4)](#syntax-extensions) section.
 
 If the Rust compiler was installed successfully, running `rustc
 hello.rs` will produce an executable called `hello` (or `hello.exe` on
@@ -1059,7 +1061,7 @@ box, while the owner holds onto a pointer to it:
     list -> | Cons | 1 | ~ | -> | Cons | 2 | ~ | -> | Cons | 3 | ~ | -> | Nil          |
             +--------------+    +--------------+    +--------------+    +--------------+
 
-> Note: the above diagram shows the logical contents of the enum. The actual
+> ***Note:*** the above diagram shows the logical contents of the enum. The actual
 > memory layout of the enum may vary. For example, for the `List` enum shown
 > above, Rust guarantees that there will be no enum tag field in the actual
 > structure. See the language reference for more details.
@@ -1114,7 +1116,7 @@ let z = x; // no new memory allocated, `x` can no longer be used
 ~~~~
 
 The `clone` method is provided by the `Clone` trait, and can be derived for
-our `List` type. Traits will be explained in detail later.
+our `List` type. Traits will be explained in detail [later](#traits).
 
 ~~~{.ignore}
 #[deriving(Clone)]
@@ -1207,8 +1209,8 @@ let ys = Cons(5, ~Cons(10, ~Nil));
 assert!(eq(&xs, &ys));
 ~~~
 
-Note that Rust doesn't guarantee [tail-call](http://en.wikipedia.org/wiki/Tail_call) optimization,
-but LLVM is able to handle a simple case like this with optimizations enabled.
+> ***Note:*** Rust doesn't guarantee [tail-call](http://en.wikipedia.org/wiki/Tail_call) optimization,
+> but LLVM is able to handle a simple case like this with optimizations enabled.
 
 ## Lists of other types
 
@@ -1218,6 +1220,9 @@ element type.
 
 The `u32` in the previous definition can be substituted with a type parameter:
 
+> ***Note:*** The following code introduces generics, which are explained in a
+> [dedicated section](#generics).
+
 ~~~
 enum List<T> {
     Cons(T, ~List<T>),
@@ -1336,9 +1341,13 @@ impl<T: Eq> Eq for List<T> {
 
 let xs = Cons(5, ~Cons(10, ~Nil));
 let ys = Cons(5, ~Cons(10, ~Nil));
+// The methods below are part of the Eq trait,
+// which we implemented on our linked list.
 assert!(xs.eq(&ys));
-assert!(xs == ys);
 assert!(!xs.ne(&ys));
+
+// The Eq trait also allows us to use the shorthand infix operators.
+assert!(xs == ys);
 assert!(!(xs != ys));
 ~~~