This leaves the `Share` trait at `std::kinds` via a `#[deprecated]` `pub use`
statement, but the `NoShare` struct is no longer part of `std::kinds::marker`
due to #12660 (the build cannot bootstrap otherwise).
All code referencing the `Share` trait should now reference the `Sync` trait,
and all code referencing the `NoShare` type should now reference the `NoSync`
type. The functionality and meaning of this trait have not changed, only the
naming.
Closes#16281
[breaking-change]
The reference manual said that code is interpreted as UTF-8 text and a implementation will normalize it to NFKC. However, rustc doesn't do any normalization now.
We may want to do any normalization for symbols, but normalizing whole text seems harmful because doing so loses some sort of information even if we choose a non-K variant of normalization.
I'd suggest removing "normalized to Unicode normalization form NFKC" phrase for the present so that the manual represents the current state properly. When we address the problem (with a RFC?), then the manual should be updated.
Closes#12388.
Reference: https://github.com/rust-lang/rust/issues/2253
The reference manual said that code is interpreted as UTF-8 text and a
implementation will normalize it to NFKC. However, rustc doesn't do
any normalization now.
We may want to do any normalization for symbols, but normalizing whole
text seems harmful because doing so loses some sort of information even
if we choose a non-K variant of normalization.
I'd suggest removing "normalized to Unicode normalization form NFKC"
phrase for the present so that the manual represents the current state
properly. When we address the problem (with a RFC?), then the manual
should be updated.
Closes#12388.
Reference: https://github.com/rust-lang/rust/issues/2253
Signed-off-by: OGINO Masanori <masanori.ogino@gmail.com>
This is the next section of the guide, and it's on pointers. It's not done yet, as I need to write the section on ownership and borrowing, but I figured I'd share the rest now, to get feedback on the rest of it while I take some time to get that right.
The start of a testing guide. This PR relies on the crates and modules one because I shuffled some stuff around, so sorry about that.
I got stuck with how to import this name with cargo. @wycats and @alexcrichton , any ideas?
This is an alternative to upgrading the way rvalues are handled in the
borrow check. Making rvalues handled more like lvalues in the borrow
check caused numerous problems related to double mutable borrows and
rvalue scopes. Rather than come up with more borrow check rules to try
to solve these problems, I decided to just forbid pattern bindings after
`@`. This affected fewer than 10 lines of code in the compiler and
libraries.
This breaks code like:
match x {
y @ z => { ... }
}
match a {
b @ Some(c) => { ... }
}
Change this code to use nested `match` or `let` expressions. For
example:
match x {
y => {
let z = y;
...
}
}
match a {
Some(c) => {
let b = Some(c);
...
}
}
Closes#14587.
[breaking-change]
Not included are two required patches:
* LLVM: segmented stack support for DragonFly [1]
* jemalloc: simple configure patches
[1]: http://reviews.llvm.org/D4705
Not included are two required patches:
* LLVM: segmented stack support for DragonFly [1]
* jemalloc: simple configure patches
[1]: http://reviews.llvm.org/D4705
This is super, super WIP, but I'm going to go get lunch for a while, and figured I'd toss my work up here in case anyone wants to see my work as I do it.
This contains a new introductory section explaining the basics of pointers, and some pitfalls that Rust attempts to solve. I'd be interested in hearing how my explanation is, as well as if this belongs here. Pointers are such a crucial concept, I don't mind having a beginners' section on them in the main docs, even though our main audience is supposed to understand them already. Reasonable people may disagree, however.
The translation is based on an early version of tutorial.md, thus most
of entries have been marked as fuzzy and actually they are incorrect.
Now tutorial.md is planed to be replaced with guide.md, so I'd suggest
removing translation files for a while.
/cc @gifnksm
The translation is based on an early version of tutorial.md, thus most
of entries have been marked as fuzzy and actually they are incorrect.
Now tutorial.md is planed to be replaced with guide.md, so I'd suggest
removing translation files for a while.
Signed-off-by: OGINO Masanori <masanori.ogino@gmail.com>
This eliminates the last vestige of the `~` syntax.
Instead of `~self`, write `self: Box<TypeOfSelf>`; instead of `mut
~self`, write `mut self: Box<TypeOfSelf>`, replacing `TypeOfSelf` with
the self-type parameter as specified in the implementation.
Closes#13885.
[breaking-change]
We now build the game at the end of the first section.
I wanted to do it as we went along, but it's too hard with these fundamentals
not in place. The rest will do the 'as we go' approach, but I think this is
better.
Simplify example in 5.2 to remove hidden `#[deriving(Show)]`. Traits haven't been introduced yet and now it's easier to just type in the code and expect it to work. Add in some examples for constructing the enum types. Explicitly expose `#![feature(struct_variant)]` in the code to make it more transparent, this bit me when I worked through the tutorial.
Add references in chapter 8 to later chapters describing `Rc`, `Gc` and `Send`. This is a simple fix for #15293.
Simplify vector indexing example in chapter 13 and removed hidden, unnecessary, code. Gave an example usage of the derived `Rand` trait in chapter 17.
Removed references to removed 'extra' crate.
Three small changes:
1. Re-organize headers in the Strings guide so they show up correctly.
2. build the strings guide with the other docs
3. include the strings guide in the list of guides
except where trait objects are involved.
Part of issue #15349, though I'm leaving it open for trait objects.
Cross borrowing for trait objects remains because it is needed until we
have DST.
This will break code like:
fn foo(x: &int) { ... }
let a = box 3i;
foo(a);
Change this code to:
fn foo(x: &int) { ... }
let a = box 3i;
foo(&*a);
[breaking-change]
5.2 Simplify example to remove hidden #[deriving(Show)].
Add example for constructing the enums.
8 Reference later sections describing rc, gc and send.
Fix for #15293.
13 Simplify BananaMania example to remove hidden code.
17 Gave an example using the derived Rand trait.
Removed references to removed 'extra' crate.
- Treat WOFF as binary files so that git does not perform newline normalization.
- Replace corrupt Heuristica files with Source Serif Pro — italics are [almost in production](https://github.com/adobe/source-serif-pro/issues/2) so I left Heuristica Italic which makes a good pair with SSP. Overall, Source Serif Pro is I think a better fit for rustdoc (cc @TheHydroImpulse). This ought to fix#15527.
- Store Source Code Pro locally in order to make offline docs freestanding. Fixes#14778.
Preview: http://adrientetar.legtux.org/cached/rust-docs/core.html
r? @alexcrichton
I'm leaving off `rustdoc` usage because it won't work unless this is a `pub fn`, and I want to talk about public/private in the context of modules. I'm also not mentioning `//!` because it is exclusively used to provide the overview of a module.
Here's the issue: https://github.com/rust-lang/rust/issues/15333
Tested it. It works. FYI, in case anyone doesn't know: keyboard shortcut `'` restricts text search to only links on Firefox allowing this to be checked easily.
One of the examples in the docs on adding documentation to rust code has an error that will cause the function to run endlessly rather than return the desired result, should someone actually implement this for some reason. While the error does not hinder the explanation of documenting code, it does look better if it is corrected.
* channel() - #[unstable]. This will likely remain forever
* sync_channel(n: int) - #[unstable with comment]. Concerns have ben raised
about the usage of the term "synchronous channel" because that generally only
applies to the case where n == 0. If n > 0 then these channels are often
referred to as buffered channels.
* Sender::send(), SyncSender::send(), Receiver::recv() - #[experimental]. These
functions directly violate the general guideline of not providing a failing
and non-failing variant. These functions were explicitly selected for being
excused from this guideline, but recent discussions have cast doubt on that
decision. These functions are #[experimental] for now until a decision is made
as they are candidates for removal.
* Sender::send_opt(), SyncSender::send_opt(), Receiver::recv_opt() - #[unstable
with a comment]. If the above no-`_opt` functions are removed, these functions
will be renamed to the non-`_opt` variants.
* SyncSender::try_send(), Receiver::try_recv() - #[unstable with a comment].
These return types of these functions to not follow general conventions. They
are consistent with the rest of the api, but not with the rest of the
libraries. Until their return types are nailed down, these functions are
#[unstable].
* Receiver::iter() - #[unstable]. This will likely remain forever.
* std::com::select - #[experimental]. The functionality is likely to remain in
some form forever, but it is highly unlikely to remain in its current form. It
is unknown how much breakage this will cause if and when the api is
redesigned, so the entire module and its components are all experimental.
* DuplexStream - #[deprecated]. This type is not composable with other channels
in terms of selection or other expected locations. It can also not be used
with ChanWriter and ChanReader, for example. Due to it being only lightly
used, and easily replaced with two channels, this type is being deprecated and
slated for removal.
* Clone for {,Sync}Sender - #[unstable]. This will likely remain forever.
* channel() - #[unstable]. This will likely remain forever
* sync_channel(n: int) - #[unstable with comment]. Concerns have ben raised
about the usage of the term "synchronous channel" because that generally only
applies to the case where n == 0. If n > 0 then these channels are often
referred to as buffered channels.
* Sender::send(), SyncSender::send(), Receiver::recv() - #[experimental]. These
functions directly violate the general guideline of not providing a failing
and non-failing variant. These functions were explicitly selected for being
excused from this guideline, but recent discussions have cast doubt on that
decision. These functions are #[experimental] for now until a decision is made
as they are candidates for removal.
* Sender::send_opt(), SyncSender::send_opt(), Receiver::recv_opt() - #[unstable
with a comment]. If the above no-`_opt` functions are removed, these functions
will be renamed to the non-`_opt` variants.
* SyncSender::try_send(), Receiver::try_recv() - #[unstable with a comment].
These return types of these functions to not follow general conventions. They
are consistent with the rest of the api, but not with the rest of the
libraries. Until their return types are nailed down, these functions are
#[unstable].
* Receiver::iter() - #[unstable]. This will likely remain forever.
* std::com::select - #[experimental]. The functionality is likely to remain in
some form forever, but it is highly unlikely to remain in its current form. It
is unknown how much breakage this will cause if and when the api is
redesigned, so the entire module and its components are all experimental.
* DuplexStream - #[deprecated]. This type is not composable with other channels
in terms of selection or other expected locations. It can also not be used
with ChanWriter and ChanReader, for example. Due to it being only lightly
used, and easily replaced with two channels, this type is being deprecated and
slated for removal.
* Clone for {,Sync}Sender - #[unstable]. This will likely remain forever.
Whew. So much here! Feedback very welcome.
This is the first part where we actually start learning things. I'd like to think I struck a good balance of explaining enough details, without getting too bogged down, and without being confusing... but of course I'd think that. 😉
As I mention in the commit comment, We probably want to move the guessing game to the rust-lang org, rather than just having it on my GitHub. Or, I could put the code inline. I think it'd be neat to have it as a project, so people can pull it down with Cargo. Until we make that decision, I'll just leave this here.
Whew! Who knew there was so much to say about variables.
We probably want to move the guessing game to the rust-lang org, rather than
just having it on my GitHub. Or, I could put the code inline. I think it'd be
neat to have it as a project, so people can pull it down with Cargo. Until we
make that decision, I'll just leave this here.
I'm going to move testing to be right AFTER the guessing game. I wanted it
to be borderline TDD, but I think that, since the first example is just one
file, it might be a bit overkill.
I'm doing this in its own commit to hopefully avoid merge conflicts.
./hello_world is not recognized on Windows.
We can type either hello_world or hello_world.exe to run the executable. I chose "hello_world.exe", which seems more conventional on Windows.
This makes the `in-header`, `markdown-before-content`, and `markdown-after-content` options available to `rustdoc` when generating documentation for any crate.
Before, these options were only available when creating documentation *from* markdown. Now, they are available when generating documentation from source.
This also updates the `rustdoc -h` output to reflect these changes. It does not update the `man rustdoc` page, nor does it update the documentation in [the `rustdoc` manual](http://doc.rust-lang.org/rustdoc.html).
floating point numbers for real.
This will break code that looks like:
let mut x = 0;
while ... {
x += 1;
}
println!("{}", x);
Change that code to:
let mut x = 0i;
while ... {
x += 1;
}
println!("{}", x);
Closes#15201.
[breaking-change]
This change registers new snapshots, allowing `*T` to be removed from the language. This is a large breaking change, and it is recommended that if compiler errors are seen that any FFI calls are audited to determine whether they should be actually taking `*mut T`.
This PR includes two big things and a bunch of little ones.
1) It enables hygiene for variables bound by 'match' expressions.
2) It fixes a bug discovered indirectly (#15221), wherein fold traversal failed to visit nonterminal nodes.
3) It fixes a small bug in the macro tutorial.
It also adds tests for the first two, and makes a bunch of small comment improvements and cleanup.
This diff will look better once bors takes care of https://github.com/rust-lang/rust/pull/15183
@brson and I talked about it, and, if I commit this skeleton, I can submit PRs for each portion, without doing this silly "builds on previous PRs" stuff, and it shouldn't cause conflicts.
This lays out what I think the guide should cover, and in what order. I haven't picked a cohesive project yet that shows all this off, but I think this progression of concepts is appropriate.
What's funny about this one is that spellcheck caught it, but for
some reason didn't give me the right suggestion, so I assumed that it
wasn't in my dictionary. Oh well.
Thanks @P1start! ❤️
This is built on top of https://github.com/rust-lang/rust/pull/15162 . cccae83d92 is the only new commit, you may want to look at that rather than the whole diff.
Writing our first Rust program together. This is the most crucial step, so I go to a fairly deep level of detail. Future sections will move more quickly.
This has my voice *very strongly*. I'm not sure if it's too much. I'd find it okay if I had to tone it back, and I don't want it to be _too strong_, but clinical docs are boring.
Yes, it is important to be careful, but repeated emphasis about it is probably
not helpful — it starts to sound like you came for a tutorial but found a
finger-wagging lecture.
Even after I removed a few of these comments, there are still several left in
the text. That's probably fine! A couple of mentions of how this is dangerous
and you ought to be careful may be a good reminder to the reader.
After making the edits, I reflowed the paragraphs that I had touched, using
emacs's "M-x fill-paragraph", with fill-column equal to 70.
This is because I observed someone reading the tutorial who thought they'd
missed something when they got to the mention of variable bindings.
This patch doesn't reflow the paragraphs so that you can see the semantic
change that I made, and a subsequent patch will reflow this paragraph.
Fixes https://github.com/rust-lang/rust/issues/13570.
Yes, it is important to be careful, but repeated emphasis about it is probably
not helpful — it starts to sound like you came for a tutorial but found a
finger-wagging lecture.
Even after I removed a few of these comments, there are still several left in
the text. That's probably fine! A couple of mentions of how this is dangerous
and you ought to be careful may be a good reminder to the reader.
After making the edits, I reflowed the paragraphs that I had touched, using
emacs's "M-x fill-paragraph", with fill-column equal to 70.
In line with what @brson, @cmr, @nikomatsakis and I discussed this morning, my
redux of the tutorial will be implemented as the Guide. This way, I can work in
small iterations, rather than dropping a huge PR, which is hard to review. In
addition, the community can observe my work as I'm doing it.
This adds a note in line with [this comment][reddit] that clarifies the state
of the tutorial, and the community's involvement with it.
[reddit]: http://www.reddit.com/r/rust/comments/28bew8/rusts_documentation_is_about_to_drastically/ci9c98k
This breaks a fair amount of code. The typical patterns are:
* `for _ in range(0, 10)`: change to `for _ in range(0u, 10)`;
* `println!("{}", 3)`: change to `println!("{}", 3i)`;
* `[1, 2, 3].len()`: change to `[1i, 2, 3].len()`.
RFC #30. Closes#6023.
[breaking-change]
If you define lang items in your crate, add `#[feature(lang_items)]`.
If you define intrinsics (`extern "rust-intrinsic"`), add
`#[feature(intrinsics)]`.
Closes#12858.
[breaking-change]
This commit makes several changes to the stability index infrastructure:
* Stability levels are now inherited lexically, i.e., each item's
stability level becomes the default for any nested items.
* The computed stability level for an item is stored as part of the
metadata. When using an item from an external crate, this data is
looked up and cached.
* The stability lint works from the computed stability level, rather
than manual stability attribute annotations. However, the lint still
checks only a limited set of item uses (e.g., it does not check every
component of a path on import). This will be addressed in a later PR,
as part of issue #8962.
* The stability lint only applies to items originating from external
crates, since the stability index is intended as a promise to
downstream crates.
* The "experimental" lint is now _allow_ by default. This is because
almost all existing crates have been marked "experimental", pending
library stabilization. With inheritance in place, this would generate
a massive explosion of warnings for every Rust program.
The lint should be changed back to deny-by-default after library
stabilization is complete.
* The "deprecated" lint still warns by default.
The net result: we can begin tracking stability index for the standard
libraries as we stabilize, without impacting most clients.
Closes#13540.
Closes#8142.
This is not the semantics we want long-term. You can continue to use
`#[unsafe_destructor]`, but you'll need to add
`#![feature(unsafe_destructor)]` to the crate attributes.
[breaking-change]
```test_harness
#[test]
fn foo() {}
```
will now compile and run the tests, rather than just ignoring & stripping them (i.e. it is as if `--test` was passed).
Also, the specific example in https://github.com/rust-lang/rust/issues/12242 was fixed (but that issue is broader than that example).
rustdoc now supports compiling things with `--test` so the examples in
this guide can be compiled & tested properly (revealing a few issues &
out-dated behaviours).
Also, reword an example to be clearer, cc #12242.
This adds the `test_harness` directive that runs a code block using the
test runner, to allow for `#[test]` items to be demonstrated and still
tested (currently they are just stripped and not even compiled, let
alone run).
This commit makes several changes to the stability index infrastructure:
* Stability levels are now inherited lexically, i.e., each item's
stability level becomes the default for any nested items.
* The computed stability level for an item is stored as part of the
metadata. When using an item from an external crate, this data is
looked up and cached.
* The stability lint works from the computed stability level, rather
than manual stability attribute annotations. However, the lint still
checks only a limited set of item uses (e.g., it does not check every
component of a path on import). This will be addressed in a later PR,
as part of issue #8962.
* The stability lint only applies to items originating from external
crates, since the stability index is intended as a promise to
downstream crates.
* The "experimental" lint is now _allow_ by default. This is because
almost all existing crates have been marked "experimental", pending
library stabilization. With inheritance in place, this would generate
a massive explosion of warnings for every Rust program.
The lint should be changed back to deny-by-default after library
stabilization is complete.
* The "deprecated" lint still warns by default.
The net result: we can begin tracking stability index for the standard
libraries as we stabilize, without impacting most clients.
Closes#13540.
Replace its usage with byte string literals, except in `bytes!()` tests.
Also add a new snapshot, to be able to use the new b"foo" syntax.
The src/etc/2014-06-rewrite-bytes-macros.py script automatically
rewrites `bytes!()` invocations into byte string literals.
Pass it filenames as arguments to generate a diff that you can inspect,
or `--apply` followed by filenames to apply the changes in place.
Diffs can be piped into `tip` or `pygmentize -l diff` for coloring.
See #14646 (tracking issue) and rust-lang/rfcs#69.
This does not close the tracking issue, as the `bytes!()` macro still needs to be removed. It will be later, after a snapshot is made with the changes in this PR, so that the new syntax can be used when bootstrapping the compiler.
`#[inline(never)]` is used.
Closes#8958.
This can break some code that relied on the addresses of statics
being distinct; add `#[inline(never)]` to the affected statics.
[breaking-change]
Previously, the type system's restrictions on borrowing were summarized as
> The previous example showed that the type system forbids any borrowing of owned boxes found in aliasable, mutable memory.
This did not jive with the example, which allowed mutations so long as the borrowed reference had been returned. Also, the language has changed to no longer allow aliasable mutable locations. This changes the summary to read
> The previous example showed that the type system forbids mutations of owned boxed values while they are being borrowed. In general, the type system also forbids borrowing a value as mutable if it is already being borrowed - either as a mutable reference or an immutable one.
This adds more general information for the experienced reader as well, to offer a more complete understanding.
The guide previously stated:
> The compiler will automatically convert a box box point to a reference like &point.
This fixes the doubled word `box`, so the statement reads
> The compiler will automatically convert a box point to a reference like &point.
The code it is referring to is `compute_distance(&on_the_stack, on_the_heap);`, so a single `box` is appropriate.
This commit is the final step in the libstd facade, #13851. The purpose of this
commit is to move libsync underneath the standard library, behind the facade.
This will allow core primitives like channels, queues, and atomics to all live
in the same location.
There were a few notable changes and a few breaking changes as part of this
movement:
* The `Vec` and `String` types are reexported at the top level of libcollections
* The `unreachable!()` macro was copied to libcore
* The `std::rt::thread` module was moved to librustrt, but it is still
reexported at the same location.
* The `std::comm` module was moved to libsync
* The `sync::comm` module was moved under `sync::comm`, and renamed to `duplex`.
It is now a private module with types/functions being reexported under
`sync::comm`. This is a breaking change for any existing users of duplex
streams.
* All concurrent queues/deques were moved directly under libsync. They are also
all marked with #![experimental] for now if they are public.
* The `task_pool` and `future` modules no longer live in libsync, but rather
live under `std::sync`. They will forever live at this location, but they may
move to libsync if the `std::task` module moves as well.
[breaking-change]
This commit is the final step in the libstd facade, #13851. The purpose of this
commit is to move libsync underneath the standard library, behind the facade.
This will allow core primitives like channels, queues, and atomics to all live
in the same location.
There were a few notable changes and a few breaking changes as part of this
movement:
* The `Vec` and `String` types are reexported at the top level of libcollections
* The `unreachable!()` macro was copied to libcore
* The `std::rt::thread` module was moved to librustrt, but it is still
reexported at the same location.
* The `std::comm` module was moved to libsync
* The `sync::comm` module was moved under `sync::comm`, and renamed to `duplex`.
It is now a private module with types/functions being reexported under
`sync::comm`. This is a breaking change for any existing users of duplex
streams.
* All concurrent queues/deques were moved directly under libsync. They are also
all marked with #![experimental] for now if they are public.
* The `task_pool` and `future` modules no longer live in libsync, but rather
live under `std::sync`. They will forever live at this location, but they may
move to libsync if the `std::task` module moves as well.
[breaking-change]
Previously, the type system's restrictions on borrowing were summarized as
> The previous example showed that the type system forbids any borrowing of owned boxes found in aliasable, mutable memory
This did not jive with the example, which allowed mutations so long as the borrowed reference had been returned. Also, the language has changed to no longer allow aliasable mutable locations. This changes the summary to read
> The previous example showed that the type system forbids mutations of owned boxed values while they are being borrowed. In general, the type system also forbids borrowing a value as mutable if it is already being borrowed - either as a mutable reference or an immutable one.
This adds more general information for the experienced reader as well, to offer a more complete understanding.
The guide previously stated:
> The compiler will automatically convert a box box point to a reference like &point.
This fixes the doubled word `box`, so the statement reads
> The compiler will automatically convert a box point to a reference like &point.
The code it is referring to is `compute_distance(&on_the_stack, on_the_heap);`, so a single `box` is appropriate.
This grows a new option inside of rustdoc to add the ability to submit examples
to an external website. If the `--markdown-playground-url` command line option
or crate doc attribute `html_playground_url` is present, then examples will have
a button on hover to submit the code to the playground specified.
This commit enables submission of example code to play.rust-lang.org. The code
submitted is that which is tested by rustdoc, not necessarily the exact code
shown in the example.
Closes#14654
* null and mut_null are unstable. Their names may change if the unsafe
pointer types change.
* copy_memory and copy_overlapping_memory are unstable. We think they
aren't going to change.
* set_memory and zero_memory are experimental. Both the names and
the semantics are under question.
* swap and replace are unstable and probably won't change.
* read is unstable, probably won't change
* read_and_zero is experimental. It's necessity is in doubt.
* mem::overwrite is now called ptr::write to match read and is
unstable. mem::overwrite is now deprecated
* array_each, array_each_with_len, buf_len, and position are
all deprecated because they use old style iteration and their
utility is generally under question.
Now that rustdoc understands proper language tags
as the code not being Rust, we can tag everything
properly. `norust` as a negative statement is a bad
tag.
This change tags examples in other languages by
their language. Plain notations are marked as `text`.
Console examples are marked as `console`.
Also fix markdown.rs to not highlight non-rust code.
Amends the documentation to reflect the new
behaviour.
Now that rustdoc understands proper language tags
as the code not being Rust, we can tag everything
properly.
This change tags examples in other languages by
their language. Plain notations are marked as `text`.
Console examples are marked as `console`.
Also fix markdown.rs to not highlight non-rust code.
Cross crate links can target items which are not rendered in the documentation.
If the item is reexported at a higher level, the destination of the link (a
concatenation of the fully qualified name) may actually lead to nowhere. This
fixes this problem by altering rustdoc to emit pages which redirect to the local
copy of the reexported structure.
cc #14515Closes#14137
Renamed `owned_box` to `on_the_heap` to use a consistent
naming across the tutorial and the life time guide.
Also it makes the example easier to grasp.
