This is a more introductory document, suitable for Part II. The arcane details move to an "Advanced macros" chapter in Part III.
Conflicts:
src/doc/trpl/macros.md
The first commit adds a short note which I believe will reduce worries in people who work with closures very often and read the Rust book for their first time.
The second commit consists solely of tiny typo fixes. In some cases, I changed "logical" quotations like
She said, "I like programming".
to
She said, "I like programming."
because the latter seems to be the prevalent style in the book.
The Rust Programming Language book has no explanation of what `i32` actually means. I have added an explanation for the first time the reader encounters this type.
@steveklabnik Trying out the Glossary idea.
Added the paragraph about 'complicated words' because I think it would be useful to those contributing to the book. Maybe this should not be here
The book in "hello-world" tells that there are configs for some programs and gives a link to main repo's src/etc. Actually, these configs moved to separate repos some days ago. This PR adds a markdown file with links and moves "hello-world" link about editors to point directly to this new file.
Highlights:
* Adds an 'uninstall.sh' script to `/usr/local/lib/rustlib/uninstall.sh`, the path to which is printed during installation.
* Components can be deselected during install, like `install.sh --without=rust-docs`.
* Components can be listed with `install.sh --list-components`.
* Vastly reduces spew during install (but supporting a `--verbose` option).
Typicall install run looks like:
```
brian@brianX1:~/dev/multirust⟫ sudo ./install.sh
[sudo] password for brian:
install: creating uninstall script at /usr/local/lib/rustlib/uninstall.sh
install: installing component 'rustc'
install: installing component 'cargo'
install: installing component 'rust-docs'
Rust is ready to roll.
```
Needs to be merged right before corresponding PRs to cargo and rust-packaging.
Fixes https://github.com/rust-lang/rust/issues/21117
Fixes https://github.com/rust-lang/rust/issues/20283
While having a look at the Rust book I found this tiny error. In my opinion this if should be all lowercase, because it follows a colon, but I am no native speaker, so I am probably wrong. Also it is a very tiny change, so feel free to include it in any bigger documentation patch.
Replaced outdated use of the `range(start, end)` function where
approriate with `start..end`, and tweaked the examples to compile and run with the latest rust. I also fixed two periphery compile issues in reference.md which were occluding whether there were any new errors created by these changes, so I fixed them.
I started to write up some docs on this, and then realized I was just repeating http://huonw.github.io/blog/2015/01/peeking-inside-trait-objects/ but worse. @huonw previously said that we can use this content if we wanted, so I made some tweaks and integrated it into the book.
Fixes#21707
#[plugin] #[no_link] extern crate bleh;
becomes a crate attribute
#![plugin(bleh)]
The feature gate is still required.
It's almost never correct to link a plugin into the resulting library /
executable, because it will bring all of libsyntax and librustc with it.
However if you really want this behavior, you can get it with a separate
`extern crate` item in addition to the `plugin` attribute.
Fixes#21043.
Fixes#20769.
[breaking-change]
Without such a clarification, people who know and love closures (for instance
programmers with a Haskell background) might fear that types would have to
be declared in closures and that therefore using closures would be much more
unwieldy.
Second try to address https://github.com/rust-lang/rust/issues/21196 . A lot that was removed at the end basically seemed repetitive showing simple variations on the same type. It seems more effective to just show more variants at the beginning instead.
If you want to pack values into an example, better to use `i32` or some digit than `String` because you don't need the `to_string()` method.
I didn't mention `derive` because:
* I can't explain it (only use it)
* I don't have a link to a good description (maybe rustbyexample but you probably want links internal)
* Giving more detail especially stating that `==` won't work and why should help quite a bit
I didn't `make test` or check links but I will if this will be merged.
@steveklabnik
This commits adds an associated type to the `FromStr` trait representing an
error payload for parses which do not succeed. The previous return value,
`Option<Self>` did not allow for this form of payload. After the associated type
was added, the following attributes were applied:
* `FromStr` is now stable
* `FromStr::Err` is now stable
* `FromStr::from_str` is now stable
* `StrExt::parse` is now stable
* `FromStr for bool` is now stable
* `FromStr for $float` is now stable
* `FromStr for $integral` is now stable
* Errors returned from stable `FromStr` implementations are stable
* Errors implement `Display` and `Error` (both impl blocks being `#[stable]`)
Closes#15138
This commits adds an associated type to the `FromStr` trait representing an
error payload for parses which do not succeed. The previous return value,
`Option<Self>` did not allow for this form of payload. After the associated type
was added, the following attributes were applied:
* `FromStr` is now stable
* `FromStr::Err` is now stable
* `FromStr::from_str` is now stable
* `StrExt::parse` is now stable
* `FromStr for bool` is now stable
* `FromStr for $float` is now stable
* `FromStr for $integral` is now stable
* Errors returned from stable `FromStr` implementations are stable
* Errors implement `Display` and `Error` (both impl blocks being `#[stable]`)
Closes#15138
Lifetime elision documentation was reference a previously existing function
that doesn't exist. After talking with Steve Klabnik, I confirmed the correct
function to be referenced and updated documentation accordingly.
Compiling won't produce an executable just yet because (as stated in the next
paragraph) there are errors. By removing this sentance, the reader won't get
confused when they expect a successful compile i.e. if they don't read ahead one
paragraph, they are going to be checking their code and wondering why it's not
compiling.
Compiling won't produce an executable just yet because (as stated in the next
paragraph) there are errors. By removing this sentance, the reader won't get
confused when they expect a successful compile i.e. if they don't read ahead one
paragraph, they are going to be checking their code and wondering why it's not
compiling.
After PR #19766 added implicit coersions `*mut T -> *const T`, the explicit casts can be removed.
(The number of such casts turned out to be relatively small).
These two attributes are used to change the entry point into a Rust program, but
for now they're being put behind feature gates until we have a chance to think
about them a little more. The #[start] attribute specifically may have its
signature changed.
This is a breaking change to due the usage of these attributes generating errors
by default now. If your crate is using these attributes, add this to your crate
root:
#![feature(start)] // if you're using the #[start] attribute
#![feature(main)] // if you're using the #[main] attribute
cc #20064
"Idiomatic code should not use extra whitespace in the middle of a line to provide alignment."
http://aturon.github.io/style/whitespace.html
I realize the linked page still needs an RFC, but the docs should be written in accordance with the guidelines nevertheless.
I searched for times when we were hiding functions with # in the documentation,
and fixed them to not use it unless neccesary.
I also made random improvements whenever I changed something. For example,
I changed Example to Examples, for consistency.
Fixes#13423
These two attributes are used to change the entry point into a Rust program, but
for now they're being put behind feature gates until we have a chance to think
about them a little more. The #[start] attribute specifically may have its
signature changed.
This is a breaking change to due the usage of these attributes generating errors
by default now. If your crate is using these attributes, add this to your crate
root:
#![feature(start)] // if you're using the #[start] attribute
#![feature(main)] // if you're using the #[main] attribute
cc #20064
Really small correction.
This anti-example in the Closures section is supposed to fail because of a borrow, but it was failing at the type inference because of insufficient type information.
This makes it fail for the expected reason.
Really small correction.
This anti-example in the Closures section is supposed to fail because of a borrow, but it was failing at the type inference because of insufficient type information.
This makes it fail for the expected reason.
uint was recently deprecated, so in following the use of i32 at first,
replace all references to uint with u32.
Also change literals from e.g. 100u to 100, so that they are no longer
usize.
`int` doesn't exist anymore. Usage of its equivalent `isize` is
discouraged since its size is platform-dependent. `i32` is used instead
in the examples. Also, integer suffixes aren't needed in the examples
anymore so we can just write `5` instead of `5i`.
Here's my PR for the changes discussed in #19823. I decided to leave `_these_` types of italics the way there were because it differentiates the use of italics for emphasis from `*key term*` italics. Otherwise, bolded terms have been changed to italics, and single and double quotes have been changed appropriately, depending on their context (my judgement may not be the best, though).
r? @steveklabnik (congratulations on #19897 being finalized and merged, by the way!)
This commit is an attempt to standardize the use of punctuation and
formatting in "The Rust Programming Language" as discussed in #19823.
- Convert bold text to italicized textcwhen referring to terminology.
- Convert single-quoted text to italicized or double-quoted text,
depending on context.
- Use double quotes only in the case of scare quotes or quotations.
This pulls all of our long-form documentation into a single document,
nicknamed "the book" and formally titled "The Rust Programming
Language."
A few things motivated this change:
* People knew of The Guide, but not the individual Guides. This merges
them together, helping discoverability.
* You can get all of Rust's longform documentation in one place, which
is nice.
* We now have rustbook in-tree, which can generate this kind of
documentation. While its style is basic, the general idea is much
better: a table of contents on the left-hand side.
* Rather than a almost 10,000-line guide.md, there are now smaller files
per section.
