Basically, the overall structure is this:
* Getting Started - getting an environment up and running
* Learn Rust - project-based learning the basics
* Effective Rust - higher level concepts that lead to writing good rust
* Syntax and Semantics - chunks of exactly what it sounds like
* Nightly Rust - unstable stuff, a staging area for documenting features
* Glossary - self-explanatory
There's a number of weaknesses with the current TOC, but I'll just focus on the strengths of the new one:
We start off with getting our environment set up. That's "getting started".
Then, we basically present you with two choices: do you want to start small, with bits of syntax? Or do you want to dive in with projects?
I'm guessing more people will choose the second, so that's the next part: "Learn Rust." I don't have any chapters here, but this would have an updated guessing game, a tutorial on building a little `wc` clone, and something else I haven't decided yet. Lots of options. But the idea is to just dive in and get your hands dirty. I'll heavily link to the 'syntax and semantics' sections that are relevant.
Then, a section I'm calling 'Effective Rust'. it feels greedy to steal that title, so I'm hoping to give it another name. These are higher-level things than syntax that Rust programmers should know: error handling is a great example. Most of these are sort of 'how do I use the standard library together' kinds of things. This also contains informations about systems programming that those new to it might not know: the stack vs the heap, for example.
Then, "Syntax and Semantics." This has one section for each bit of Rust. Small, focused, but explains _everything_. These are positioned to be almost entirely in-order, but heavily cross-link, so you can go out of order if you want to, but you can also use it as a reference.
Next, "Nightly Rust," where documenting unstable things goes. If we want to get good feedback on new features, they'll need to be documented, but we don't want to taint the main docs, so that's what this is for.
Finally, the glossary. Straightforward enough.
--------------------------------
This is going to be a terrible PR to review, so I just did the TOC re-organization, with basically no editing. So it'll be a bit jumbled at first. But next steps are to go through and edit / revise / tweak / add stuff to get it in tip-top shape for 1.0!
As beta is now released and is "suggested" version of `rustc` then there should be no code (in documentation) that will not compile with it. This one does not.
So according to [this great talk](http://delete-your-code.herokuapp.com/), I am doing what should be done.
I think "let is used to introduce variables" is incorrent.
You can use
```rust
match (42, true) {
(x, y) => { /* ... */ }
}
```
to replace
```rust
let x = 42;
let y = true;
```
so it's nothing special for `let`.
I've taken another look at extended errors - fixing up the printing and adding a few more for match expressions.
With regards to printing, the previous behaviour was to just print the error message string directly, despite it containing indentation which caused it to overflow the standard terminal width of 80 columns (try `rustc --explain E0004`). The first approach I considered was to strip the leading whitespace from each line and lay out the text dynamically, inserting spaces in between. This approach became quite messy when taking multi-paragraph errors into account (and seemed overkill). The approach I settled on removes the indentation in the string itself and begins each message with a newline that is stripped before printing.
I feel like complete extended errors would be nice to have for 1.0.0 and I'm happy to spearhead an effort to get them written. Brian got me onto writing them at an SF meetup and I think it shouldn't be too hard to get the remaining 80 or so written with the help of people who don't really work on compiler innards.
A recent change to the implementation of range iterators meant that,
even when stepping by 1, the iterators *always* involved checked
arithmetic.
This commit reverts to the earlier behavior (while retaining the
refactoring into traits).
Fixes#24095Closes#24119
cc #24014
r? @alexcrichton
Addresses issue #22425. See `src/test/compile-fail/macro-incomplete-parse.rs` for a relevant test:
macro-incomplete-parse.rs:15:9: 15:10 error: macro expansion ignores token `,` and any following
macro-incomplete-parse.rs:15 , //~ ERROR macro expansion ignores token `,`
^
macro-incomplete-parse.rs:27:1: 27:17 note: caused by the macro expansion here; the usage of `ignored_item` is likely invalid in this context
macro-incomplete-parse.rs:27 ignored_item!();
^~~~~~~~~~~~~~~~
macro-incomplete-parse.rs:20:14: 20:15 error: macro expansion ignores token `,` and any following
macro-incomplete-parse.rs:20 () => ( 1, 2 ) //~ ERROR macro expansion ignores token `,`
^
macro-incomplete-parse.rs:30:5: 30:21 note: caused by the macro expansion here; the usage of `ignored_expr` is likely invalid in this context
macro-incomplete-parse.rs:30 ignored_expr!();
^~~~~~~~~~~~~~~~
macro-incomplete-parse.rs:24:14: 24:15 error: macro expansion ignores token `,` and any following
macro-incomplete-parse.rs:24 () => ( 1, 2 ) //~ ERROR macro expansion ignores token `,`
^
macro-incomplete-parse.rs:32:9: 32:23 note: caused by the macro expansion here; the usage of `ignored_pat` is likely invalid in this context
macro-incomplete-parse.rs:32 ignored_pat!() => (),
^~~~~~~~~~~~~~
This does not address the case of improper expansion inside of an impl { } as seen in issue #21607.
I'm not sure if the note text is ideal, but it can be refined if needed.
A recent change to the implementation of range iterators meant that,
even when stepping by 1, the iterators *always* involved checked
arithmetic.
This commit reverts to the earlier behavior (while retaining the
refactoring into traits).
Fixes#24095
cc #24014
In addition to being nicer, this also allows you to use `sum` and `product` for
iterators yielding custom types aside from the standard integers.
Due to removing the `AdditiveIterator` and `MultiplicativeIterator` trait, this
is a breaking change.
[breaking-change]
@mahkoh points out in #15628 that unicode.py does not use
normative data for Grapheme classes. This pr fixes that issue,
and does some minor cleanup of the unicode.py script.
In addition, GC_RegionalIndicator is renamed GC_Regional_Indicator
in order to stay in line with the Unicode class name definitions.
I have updated refs in u_str.rs, and verified that there are no
refs elsewhere in the codebase. However, in principle someone
using the unicode tables for their own purposes might see breakage
from this.
* Fix broken \"module-level documentation\" link on the [`trait Any` docs](http://doc.rust-lang.org/std/any/trait.Any.html) and related broken markup on the [`std::any` docs](http://doc.rust-lang.org/std/any/index.html).
* Remove an outdated or incorrect notice in the `BufRead::lines` docs. There is no such `read_string` function, and `lines` never returns an error.
r? @steveklabnik
traits.md said:
If we add a `use` line right above `main` and make the right things public,
everything is fine:
However, the use line was actually placed at the top of the file instead. Move
the use line to right above main. That also makes the example more evocative
of cases where the module is defined in a separate file.
Fixes#24030
Of the four code samples with modules in TRPL:
- 2 use `mod test`
- 2 use `mod tests`
We should be consistent here, but which is right? The stdlib is split:
$ grep -r 'mod tests {' src/lib* | wc -l
63
$ grep -r 'mod test {' src/lib* | wc -l
58
Subjectively, I like the plural, but both the language reference and the
style guide recommend the singular. So we'll go with that here, for now.
r? @steveklabnik
Because the current style for `code` in rustdoc is to prewrap whitespace, code spans that are hard wrapped in the source documentation are prematurely wrapped when rendered in HTML. [For example][2],
```
/// ...
/// type can be borrowed as multiple different types. In particular, `Vec<T>:
/// Borrow<Vec<T>>` and `Vec<T>: Borrow<[T]>`.
```
renders as
because "`Vec<T>: Borrow<Vec<T>>`" wraps to the next line in the source.
CommonMark 0.18 [[1]] specifies "interior spaces and line endings are collapsed into single spaces" for code spans, which would actually prevent this issue, but hoedown does not currently conform to the
CommonMark spec.
The added span-level callback attempts to adhere to how whitespace is handled as described by CommonMark, fixing the issue of early, unintentional wrapping of code spans in rendered HTML.
[1]: http://spec.commonmark.org/0.18/
[2]: https://doc.rust-lang.org/std/borrow/trait.Borrow.html
The current help string ("space separated list") suggests that `--passes "pass1 pass2"` is expected; the orrect usage is `--passes pass1 --passes pass2`.
This adds the missing methods and turns `str::pattern` in a user facing module, as per RFC.
This also contains some big internal refactorings:
- string iterator pairs are implemented with a central macro to reduce redundancy
- Moved all tests from `coretest::str` into `collectionstest::str` and left a note to prevent the two sets of tests drifting apart further.
See https://github.com/rust-lang/rust/issues/22477
@mahkoh points out in #15628 that unicode.py does not use
normative data for Grapheme classes. This pr fixes that issue.
In addition, GC_RegionalIndicator is renamed GC_Regional_Indicator
in order to stay in line with the Unicode class name definitions.
I have updated refs in u_str.rs, and verified that there are no
refs elsewhere in the codebase. However, in principle someone
using the unicode tables for their own purposes might see breakage
from this.
Hello!
I've been working towards a libsyntax without panics. See:
http://internals.rust-lang.org/t/changing-libsyntax-to-use-result-instead-of-panic/1670
This patch changes the internals of parser.rs to use Result<> rather than panicing. It keeps the following old-style panicing functions as a facade:
parse_expr, parse_item, parse_pat, parse_arm, parse_ty, parse_stmt
I left these functions because I wasn't sure what to do about the quote_* macros or how many syntax-extensions would break if these and quoting macros returned Result.
The gyst of the rest of the patch is:
- Functions in parse/parser.rs return PResult<> rather than panicing
- Other functions in libsyntax call panic! explicitly if they rely on panicing behaviour.
- I added a macro 'panictry!()' to act as scaffolding for callers while converting panicing functions. (This does the same as 'unwrap()' but is easier to grep for and turn into try!()).
Am I on the right track? I'd quite like to get something merged soon as keeping this rebased in the face of libsyntax changes is a lot of work. Please let me know what changes you'd like to see to make this happen.
Thanks!, Phil
Because the current style for `code` in rustdoc is to prewrap
whitespace, code spans that are hard wrapped in the source
documentation are prematurely wrapped when rendered in HTML.
CommonMark 0.18 [[1]] specifies "interior spaces and line endings are
collapsed into single spaces" for code spans, which would actually
prevent this issue, but hoedown does not currently conform to the
CommonMark spec.
The added span-level callback attempts to adhere to how whitespace is
handled as described by CommonMark, fixing the issue of early,
unintentional wrapping of code spans in rendered HTML.
[1]: http://spec.commonmark.org/0.18/
