Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Minor doc fixes in "Crates and Modules" and "Lifetimes" chapters #32634

Merged
merged 2 commits into from
Apr 6, 2016
Merged

Minor doc fixes in "Crates and Modules" and "Lifetimes" chapters #32634

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d841c15
Doc fix: function takes argument by reference.
Mar 31, 2016
a7d15ce
Doc fix: list all module files Rust looks for.
Mar 31, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions src/doc/book/crates-and-modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ build deps examples libphrases-a7448e02a0468eaa.rlib native
`libphrases-hash.rlib` is the compiled crate. Before we see how to use this
crate from another crate, let’s break it up into multiple files.

# Multiple file crates
# Multiple File Crates

If each crate were just one file, these files would get very large. It’s often
easier to split up crates into multiple files, and Rust supports this in two
Expand Down Expand Up @@ -190,13 +190,19 @@ mod farewells;
```

Again, these declarations tell Rust to look for either
`src/english/greetings.rs` and `src/japanese/greetings.rs` or
`src/english/farewells/mod.rs` and `src/japanese/farewells/mod.rs`. Because
these sub-modules don’t have their own sub-modules, we’ve chosen to make them
`src/english/greetings.rs` and `src/japanese/farewells.rs`. Whew!

The contents of `src/english/greetings.rs` and `src/japanese/farewells.rs` are
both empty at the moment. Let’s add some functions.
`src/english/greetings.rs`, `src/english/farewells.rs`,
`src/japanese/greetings.rs` and `src/japanese/farewells.rs` or
`src/english/greetings/mod.rs`, `src/english/farewells/mod.rs`,
`src/japanese/greetings/mod.rs` and
`src/japanese/farewells/mod.rs`. Because these sub-modules don’t have
their own sub-modules, we’ve chosen to make them
`src/english/greetings.rs`, `src/english/farewells.rs`,
`src/japanese/greetings.rs` and `src/japanese/farewells.rs`. Whew!
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why was this change made?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The english and japanese modules each contain two sub-modules - greetings and farewells. These means that the compiler must look for a total of eight different module files - four that reside directly under the english and japanese directories - src/{english,japanese}/{greetings,farewells}.rs and four (mod.rs files) that reside under the greetings and farewells directories - src/{english,japanese}/{greetings,farewells}/mod.rs. The documentation listed only four of these - src/{english,japanese}/greetings.rs and src/{english,japanese}/farewells/mod.rs, which confused me. I thought it would be good if we listed out all the files that the compiler possibly looks for to prevent further confusion.

Also, the sentence "Because these sub-modules don't have their own....." seemed to indicate that only two files - src/english/greetings.rs and src/japanese/farewells.rs need to be created, but in actuality four files need to be created - src/{english,japanese}/{greetings/farewells}.rs. This commit fixes this too.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh! Sorry about this, I misunderstood. I see now.


The contents of `src/english/greetings.rs`,
`src/english/farewells.rs`, `src/japanese/greetings.rs` and
`src/japanese/farewells.rs` are all empty at the moment. Let’s add
some functions.

Put this in `src/english/greetings.rs`:

Expand Down
4 changes: 2 additions & 2 deletions src/doc/book/lifetimes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,8 @@ To fix this, we have to make sure that step four never happens after step
three. The ownership system in Rust does this through a concept called
lifetimes, which describe the scope that a reference is valid for.

When we have a function that takes a reference by argument, we can be implicit
or explicit about the lifetime of the reference:
When we have a function that takes an argument by reference, we can be
implicit or explicit about the lifetime of the reference:

```rust
// implicit
Expand Down