(Mini) Rollup of 15 pull requests #23660
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Member
Manishearth
commented
Mar 24, 2015
Manishearth
commented
- Successful merges: Docs: guide copy edits, subjective improvements, and other suggestions #22954, Stabilize Entry types #23509, Add note about pointer state after the call. #23561, fix the reference #23590, Derive missing trait implementations for cursor #23607, Refine Cursor docstring #23608, Remove bad reference to std::io #23615, Document how to document macros #23618, Re-word explanation on closures in intro #23619, Beef up BufRead::consume docs #23622, Fix dead link for std::sync::mpsc. #23634, Make note of str in 'more strings' chapter #23639, Clarify that slices don't just point to arrays #23641, Update docs for ptr module. #23644, Don't conflate regions and affine types #23645
- Failed merges: book: some Crates and Modules nits #23401
This commit marks as `#[stable]` the `Entry` types for the maps provided by `std`. The main reason these had been left unstable previously was uncertainty about an eventual trait design, but several plausible designs have been proposed that all work fine with the current type definitions.
PR rust-lang#23104 moved `is_null` and `offset` to an inherent impl on the raw pointer type.
Greetings Rustaceans! I've just been getting acquainted with Rust through the guide. First let me say that it's already in great shape, chapters are kept a good length to be digestible and paced to move the reader along fluidly, so my compliments to contributors! Along the way I noticed a few minor copy errors, and also a few areas that I thought more subjectively could stand to be improved. My commits here are divided so that minor edits unlikely to be very contentious could be cherry-picked, and then topically on parts that might generate more discussion. I also have some comments and questions that aren't directly associated with any changes on this branch yet. I'm not sure how you like to triage this sort of thing but I'll present them below and if it's appropriate they could be moved to separate issues or I might be able to help work some of them out within the scope of this PR. Sorry that these are a lot to take in, pretty much everything below here can be digested independently of the current changes in this PR so you could read the rest later 😄 ### Questions and Comments I'll give stable links to doc revisions as of this writing. 1. The [example using `PartialEq` in the Traits chapter][1] is poor—we have no idea how `PartialEq` works at this point in the text (or at any point, AFAICT), so it isn't clear why it won't work as a trait bound in this situation and `Float` almost magically does, with the aid of existing tailor-made identity functions that seem unlikely to be so conveniently available when we encounter a scenario like this in our real-world code. This section just seems glossed over, or perhaps content has moved around over time or there's an assumption that implementing equality with `PartialEq` should be covered in the guide eventually so this example will be less foreign. As it stands the text is hard to follow and not very meaningful. 2. I found treatment of the relationship of trait objects to pointers in the *Static and Dynamic Dispatch* chapter unclear. [The "Why Pointers?" section][2] opens with this line: > The use of language like "fat pointer" implies that a trait object is always a pointer of some form, but why? But the phrase "fat pointer" hasn't been used anywhere before. This is some of the more complex material in the guide, but this section nevertheless feels displaced, not clearly connecting preceding subject matter. Earlier we've covered the internal representation of trait objects and significance of pointers they contain, but it hasn't been spelled out (other than what `&Foo` syntax suggests) that trait objects are references (and why). That's what the "Why Pointers?" section is aiming to do I gather, but it seems out of place, I think it'd make more sense to cover this before the gory details of their internals. 3. Suggestion: move the *Error Handling* chapter much earlier in the Intermediate section of the guide, or even into the Basics section. I know the Intermediate section isn't intended to be read in order per se, but plenty of people like me are just going to read it straight through anyway 😁 These are pretty fundamental concepts to understand and `Option`, `Result`, and idioms like `unwrap()` and `.ok().expect()` are referenced numerous times throughout the rest of the guide. They feature pretty prominently as early as *Standard Input* and *Guessing Game* chapters in Basics, in fact. I happen to have a good understanding of these already through encountering their analogs in typed functional languages, but if I didn't I believe I really would have appreciated reading *Error Handling* much earlier. 4. In the `rustdoc` chapter, a [comment at the beginning of the first source example][3] refers to a "link" crate attribute being needed. There seems to be no such attribute present in the source. I believe this refers to `crate_type` [according to the reference][4], but it'd be nice if this example were updated/clarified (I think `crate_id` is deprecated/obsolete too). This brings me to a related comment also: after encountering crate attributes in the reference and also docs on Cargo configuration like `crate-type = ["dylib"]`, I'm uncertain about the relationship/redundancy between these. I'm sure this is the kind of thing where docs are simply struggling to keep pace with rapid changes in Rust and Cargo, just wanted to flag that this distinction ought to be clearly covered in the docs for one or the other at some point, it's presently hard to track down. 5. Minor: link to sample editor configurations in [the introductory chapter][5] is broken, probably the generator automatically translates `.md` links to `.html`. Perhaps it shouldn't do that for absolute URLs. 6. Following from my changes to the enums coverage in [*Compound Data Types*][6] in this PR: sum types are an important topic and I tried to make some improvements, but I think the motivating example of `Character` with `Digit(i32)` and `Other` variants is a pretty weak one, and a better example could greatly improve cohesion with the `Ordering` coverage later in the section and how that ties into pattern matching in the subsequent chapter. I just haven't thought of a better example to suggest yet. In particular, the text states: > This may seem rather limiting, but it's a limitation which we can overcome. This is referring to `Character`, and actually to more than one limitation: the preceding admonition that its variants aren't comparable/don't have ordering, and don't support binary operators like `*` and `+`. Overcoming these limitations actually never gets explained—we next cover how `Ordering` works as an enum itself for plain `i32`s, but never get around to showing how this might be applied to our `Digit` variant type. Since the coverage of enums already segues into pattern matching and this could be even tighter with a stronger example, it might be nice if our example enum were somehow connected to the final example program for the Basics section too, where `Ordering` reappears. I don't see how it would fit with the current guessing game example, but food for thought. 7. `#[derive]` seems conspicuously missing from the guide. It would probably make sense to introduce after showing simple examples of implementing equality and/or ordering traits by hand, which have been mentioned as possibilities above. Perhaps it's too much to breach this as early as the Basic section though without traits being introduced. `#[derive]` itself and the derivable traits can certainly be saved for Intermediate and referenced as covered later, in any case. r? @steveklabnik for docs. [1]: https://github.com/rust-lang/rust/blob/157614249594f187f421cd97f928e64c5ab5c1fa/src/doc/trpl/traits.md#our-inverse-example [2]: https://github.com/rust-lang/rust/blob/157614249594f187f421cd97f928e64c5ab5c1fa/src/doc/trpl/static-and-dynamic-dispatch.md#why-pointers [3]: https://github.com/rust-lang/rust/blob/157614249594f187f421cd97f928e64c5ab5c1fa/src/doc/trpl/documentation.md#creating-documentation [4]: http://doc.rust-lang.org/reference.html#linkage [5]: https://github.com/rust-lang/rust/blob/157614249594f187f421cd97f928e64c5ab5c1fa/src/doc/trpl/hello-world.md [6]: https://github.com/rust-lang/rust/blob/157614249594f187f421cd97f928e64c5ab5c1fa/src/doc/trpl/compound-data-types.md#enums
This commit marks as `#[stable]` the `Entry` types for the maps provided by `std`. The main reason these had been left unstable previously was uncertainty about an eventual trait design, but several plausible designs have been proposed that all work fine with the current type definitions. r? @gankro
Fixes rust-lang#23571 I _think_ this is better, but other suggestions welcome too.
Fixes rust-lang#21305 Not sure if we should include more than this here, but it should be good to have at least this.
PR rust-lang#23104 moved `is_null` and `offset` to an inherent impl on the raw pointer type. I'm not sure whether or how it's possible to link to docs for that impl. r? @steveklabnik
|
r? @pcwalton (rust_highfive has picked a reviewer for you, use r? to override) |
|
@bors: r+ p=100 |
|
📌 Commit 01a7947 has been approved by |
Manishearth
changed the title
|
The last failure on #23654 I believe was spurious, so closing in favor of that one (hopefully will land soon!) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.