4 ms·

Conditional compilation? There's still just a placeholder referring to the first version of the book or the reference. https://doc.rust-lang.org/book/conditiona

by lambda 8y ago

Conditional compilation? There's still just a placeholder referring to the first version of the book or the reference. https://doc.rust-lang.org/book/conditional-compilation.html https://doc.rust-lang.org/book/conditional-compilation.html pub(crate) doesn't seem to be mentioned in https://doc.rust-lang.org/book/ch07-02-modules-and-use-to-control-scope-and-privacy.html https://doc.rust-lang.org/book/ch07-02-modules-and-use-to-co.... Some things that are covered are a bit hard to find. For example, I didn't know if operator overloading was covered; it turns out, it's mentioned in https://doc.rust-lang.org/book/ch19-03-advanced-traits.html https://doc.rust-lang.org/book/ch19-03-advanced-traits.html, but it's not in the outline and there's no table of contents on that page, and it's only actually mentioned as an example of how default generic type parameters work. The topic it is covered well by the `std::ops` docs (https://doc.rust-lang.org/std/ops/index.html https://doc.rust-lang.org/std/ops/index.html), but since it's a language feature as well as a library feature, I'd expect it to be covered by the book as well. Raw string literals are only covered very briefly in the appendix: https://doc.rust-lang.org/book/appendix-02-operators.html https://doc.rust-lang.org/book/appendix-02-operators.html #[path = "path/to/file.rs"] doesn't seem to be mentioned; there are probably a bunch of other obscure attributes like this that aren't mentioned. repr? I didn't find any mention of #[repr(C)], #[repr(packed)], #[repr(align)] etc. I also didn't find union. simd? Seems to only really be covered by the 2018 edition guide. Googling "rust simd" turns up references to the old, unstable std::simd. The first two examples are a couple of things I've recently looked for and couldn't find; the others are ones that I noticed browsing around just now looking for other things that might have been missed. Now, some of these are documented in the reference, in the nomicon, in the 2018 edition guide, or in the standard library docs. But that's one of the problems; that there's no one, or even two or three, places you can go to find everything you need. The reference has large warnings at the top about being incomplete, although it's actually not as incomplete as I remember, it might be a good idea to remove the scary warning from it, or to do an audit of it and only put the warning on the sections that are found to be incomplete (like the memory model, which is clearly incomplete as it hasn't actually been formalized yet), but take it off of the sections that actually are up to date. And Google doesn't always help. It still sometimes gives me first edition book links at the top. When I was trying to look up all of the `#[cfg(target_...)]` forms I could use, I tried to search for "rust cfg target", https://www.google.com/search?q=rust+cfg+target https://www.google.com/search?q=rust+cfg+target, but that gives me Rust By Example, a first edition link, and a link to a placeholder that refers to both the first edition and the reference. It took a lot of clicking through to actually find the reference page on it.

steveklabnik 8y ago
Thanks! So I think that some of this difference is that you're mostly describing library features, not language features. It's also true that some of these examples blur the lines. I'm going to make some notes. > it might be a good idea to remove the scary warning from it, or to do an audit of it and only put the warning on the sections that are found to be incomplete Completeness is hard, as you've seen with the book! This is what we'd like to do, but it's non-trivial.
- lambda 8y ago
  I'd say that most of these are language features. The only that are mostly library features are operator overloading and simd, but they both have associated language features supporting them. I agree that completeness is hard, but I feel like it could be a bit easier if there were some consolidation of the material. At the very least, make sure that everything covered in the 2018 edition guide is also covered in the Book, in at least a similar level of detail. I'd also make sure that everything covered in the Reference is covered in the Book, or the Book provides at least an introduction to the topic and then a reference to the more detailed information in the Reference.
  - steveklabnik 8y ago
    > I'd also make sure that everything covered in the Reference is covered in the Book, They have very different goals, so this will never happen. The Book's job is to teach you how to program in Rust. The referece's goal is to (eventually) be a full specification. The former must be a sub-set of the latter. I do agree that everything should be documented, but the book cannot cover every last possible thing.
    - lambda 8y ago
      Yes, that's why I included the second part, "or the Book provides at least an introduction to the topic and then a reference to the more detailed information in the Reference." For example, I don't think that every last detail of #[repr(...)] needs to be covered in the Book; but as the entry point for most people, it's how they discover features, so it should at least provide an introduction, and link to the reference for more information. Likewise, while I think that the std::ops documentation does a good job of covering all of the details of operator overloading, I think the Book could provide a slightly more discoverable introduction to operator overloading which isn't just being used as an example of another feature, default generic type parameters, and provide some links to std::ops which might help with the Googleability problem. One thing that I think really needs to be focused on is some SEO for the docs. For some reason, the way the Rust docs have been organized over the years, with old versions of docs and the old book being replaced by the new one, means that a lot of times, when I search for something I find old, out of date docs. For instance, with operator overloading, if I search for "rust operator overloading", I find Rust by Example, which is OK but has a lot of text in comments which is harder to read, followed by a first edition link which warns about being out of date and then provides a link to the new book but not where in it to look, as well as a link to the 1.30.0 version of the first edition book, then a link to std::ops (which if I were a newcomer, I might not realize was relevant), then a 1.5.0 edition of the book. The first edition operator overloading chapter seems pretty reasonable, actually, and it's present in the table of contents so its more discoverable, and it contains a link to `std::ops`. But because of the new structure of the second edition book, the first page I see if I try to check the book tells me that it's outdated, and directs me to the new book in which this material is harder to find. And in the new book, even once I find it, there's not much to direct me to where to learn more about the topic. There's no link to `std::ops` documentation; I have to separately look that up. Part of the problem was that the first edition book was a bit more like a more accessible reference, while the second edition has a more narrative or tutorial structure. So there's no longer a place to go for an accessible reference to all of the language features. There's the Reference, but that's written for detail and precision and not accessibility, and as discussed, is incomplete. There's Rust by Example, but that's mostly just code examples with commentary in comments. The second edition book covers a lot of the same material as the first edition, but because of the different structure, some of the "reference information" on more advanced features is just buried in a couple of "Advanced X" chapters. I'm not sure of the best way to address this; I admit that getting this right isn't easy. One option might be to have the new book be in two halves; one of which was the narrative/tutorial portion; chapters 1 through 18, and 20, perhaps, though they might be able to be slimmed down a bit and some material moved to the second portion. The other half which is more of an "accessible reference" for advanced features; the material in chapter 19, but expanded a bit and with more discoverable per-topic chapters like the "Syntax and Semantics" section of the first book, plus the Nomicon material, and any of the topics which are missing. Or, alternatively, just expanding on and integrating the "advanced X" material, Nomicon, and missing topics into the overall structure of the book. Or another option would be to have the Book just be the Book focusing on the main narrative/tutorial introduction to the most common features, and have a Reference in two portions; one longer one which covers every major feature but in an accessible style with examples, followed by a more formal appendix covering each last little detail. I guess ultimately what I'm saying (sorry for taking so long and so many diversions to say it, but as you point out, it is hard to get this right, and I've been thinking about what I'd be looking for as I write), is that there should be some place that has an "accessible reference" to all major features which is organized somewhat like the "syntax and semantics" section of the first edition book. The second edition book, chapters 1 through 18, is definitely a better organization as a book than the first edition, but that structure doesn't lend itself well to covering every feature, and as you point out, you wouldn't want it to. But the Reference also isn't a friendly place to point people, both because of the "incomplete" warnings but also because it's written in a more formal style. And the fragmentation into the Book, Nomicon, Rust by Example, stdlib docs, 2018 Edition Guide, Cookbook, Reference, Cargo Guide, Unstable Book, along with some of the reorgs along the way, can sometimes make it a bit hard to figure out the right place to look. I feel like there should be one document somewhere that has a reasonable accessible introduction, with examples, to every feature, in addition to the more formal and succinct Reference. Maybe I should put my money where my mouth is and try to compile something like what I mean. It would help to have a little bit of buy in from docs team leadership, though, so that there would be a hope of it getting merged and maintained. Perhaps a docs RFC would be appropriate?

by lambda 8y ago

steveklabnik 8y ago

Thanks! So I think that some of this difference is that you're mostly describing library features, not language features. It's also true that some of these examples blur the lines. I'm going to make some notes. > it might be a good idea to remove the scary warning from it, or to do an audit of it and only put the warning on the sections that are found to be incomplete Completeness is hard, as you've seen with the book! This is what we'd like to do, but it's non-trivial.

lambda 8y ago
I'd say that most of these are language features. The only that are mostly library features are operator overloading and simd, but they both have associated language features supporting them. I agree that completeness is hard, but I feel like it could be a bit easier if there were some consolidation of the material. At the very least, make sure that everything covered in the 2018 edition guide is also covered in the Book, in at least a similar level of detail. I'd also make sure that everything covered in the Reference is covered in the Book, or the Book provides at least an introduction to the topic and then a reference to the more detailed information in the Reference.
- steveklabnik 8y ago
  > I'd also make sure that everything covered in the Reference is covered in the Book, They have very different goals, so this will never happen. The Book's job is to teach you how to program in Rust. The referece's goal is to (eventually) be a full specification. The former must be a sub-set of the latter. I do agree that everything should be documented, but the book cannot cover every last possible thing.
  - lambda 8y ago
    Yes, that's why I included the second part, "or the Book provides at least an introduction to the topic and then a reference to the more detailed information in the Reference." For example, I don't think that every last detail of #[repr(...)] needs to be covered in the Book; but as the entry point for most people, it's how they discover features, so it should at least provide an introduction, and link to the reference for more information. Likewise, while I think that the std::ops documentation does a good job of covering all of the details of operator overloading, I think the Book could provide a slightly more discoverable introduction to operator overloading which isn't just being used as an example of another feature, default generic type parameters, and provide some links to std::ops which might help with the Googleability problem. One thing that I think really needs to be focused on is some SEO for the docs. For some reason, the way the Rust docs have been organized over the years, with old versions of docs and the old book being replaced by the new one, means that a lot of times, when I search for something I find old, out of date docs. For instance, with operator overloading, if I search for "rust operator overloading", I find Rust by Example, which is OK but has a lot of text in comments which is harder to read, followed by a first edition link which warns about being out of date and then provides a link to the new book but not where in it to look, as well as a link to the 1.30.0 version of the first edition book, then a link to std::ops (which if I were a newcomer, I might not realize was relevant), then a 1.5.0 edition of the book. The first edition operator overloading chapter seems pretty reasonable, actually, and it's present in the table of contents so its more discoverable, and it contains a link to `std::ops`. But because of the new structure of the second edition book, the first page I see if I try to check the book tells me that it's outdated, and directs me to the new book in which this material is harder to find. And in the new book, even once I find it, there's not much to direct me to where to learn more about the topic. There's no link to `std::ops` documentation; I have to separately look that up. Part of the problem was that the first edition book was a bit more like a more accessible reference, while the second edition has a more narrative or tutorial structure. So there's no longer a place to go for an accessible reference to all of the language features. There's the Reference, but that's written for detail and precision and not accessibility, and as discussed, is incomplete. There's Rust by Example, but that's mostly just code examples with commentary in comments. The second edition book covers a lot of the same material as the first edition, but because of the different structure, some of the "reference information" on more advanced features is just buried in a couple of "Advanced X" chapters. I'm not sure of the best way to address this; I admit that getting this right isn't easy. One option might be to have the new book be in two halves; one of which was the narrative/tutorial portion; chapters 1 through 18, and 20, perhaps, though they might be able to be slimmed down a bit and some material moved to the second portion. The other half which is more of an "accessible reference" for advanced features; the material in chapter 19, but expanded a bit and with more discoverable per-topic chapters like the "Syntax and Semantics" section of the first book, plus the Nomicon material, and any of the topics which are missing. Or, alternatively, just expanding on and integrating the "advanced X" material, Nomicon, and missing topics into the overall structure of the book. Or another option would be to have the Book just be the Book focusing on the main narrative/tutorial introduction to the most common features, and have a Reference in two portions; one longer one which covers every major feature but in an accessible style with examples, followed by a more formal appendix covering each last little detail. I guess ultimately what I'm saying (sorry for taking so long and so many diversions to say it, but as you point out, it is hard to get this right, and I've been thinking about what I'd be looking for as I write), is that there should be some place that has an "accessible reference" to all major features which is organized somewhat like the "syntax and semantics" section of the first edition book. The second edition book, chapters 1 through 18, is definitely a better organization as a book than the first edition, but that structure doesn't lend itself well to covering every feature, and as you point out, you wouldn't want it to. But the Reference also isn't a friendly place to point people, both because of the "incomplete" warnings but also because it's written in a more formal style. And the fragmentation into the Book, Nomicon, Rust by Example, stdlib docs, 2018 Edition Guide, Cookbook, Reference, Cargo Guide, Unstable Book, along with some of the reorgs along the way, can sometimes make it a bit hard to figure out the right place to look. I feel like there should be one document somewhere that has a reasonable accessible introduction, with examples, to every feature, in addition to the more formal and succinct Reference. Maybe I should put my money where my mouth is and try to compile something like what I mean. It would help to have a little bit of buy in from docs team leadership, though, so that there would be a hope of it getting merged and maintained. Perhaps a docs RFC would be appropriate?