3 ms·

I have one gripe about Rust: The Rust people appear to be actively proud of their documentation, and they appear to be proud of their memory model. But the do

I have one gripe about Rust: The Rust people appear to be actively proud of their documentation, and they appear to be proud of their memory model. But the documentation of the memory model in the reference manual is seven short paragraphs of waffle, mostly defining various words in terms of other undefined words. I was mildly surprised at the state of the reference manual when they declared 1.0, and I'm distinctly disappointed that it's still so bad.

steveklabnik 8y ago
This is because this aspect of Rust is simply not yet defined. There are people working on it. Once it's agreed upon, it will be well-documented. Outside of the memory model, there's been a few people putting a lot of work into the reference lately; it's been growing a lot. It's a tricky problem.
- mjw1007 8y ago
  That's perhaps an excuse for having imperfect documentation. I don't think it's an excuse for it being in the state it's currently in. Have you looked at that chapter recently? It starts by saying « A Rust program's memory consists of a static set of items and a heap », and literally two sentences later it's talking about «the stack» as if the reader is supposed to know what that is (and as if there's only one stack).
  - steveklabnik 8y ago
    Sure. Please file bugs about stuff like this: https://github.com/rust-lang-nursery/reference/issues/new https://github.com/rust-lang-nursery/reference/issues/new That section of the reference is basically inherited from the very old days. Most of the work has been focused on the other parts. Sometimes it takes an outside perspective to notice these kinds of things. I appreciate you bringing it up. Filing a bug means that it won't get lost. If you don't want to, then I'm happy to on your behalf.
kibwen 8y ago
The Rust memory model is basically "the C11 memory model, except static checks prevent the unsound parts". We don't have much of a choice, given that we basically pretend to be C at the LLVM IR level and that we want to heavily leverage LLVM's existing optimization passes, which were designed with C in mind. The "reference" isn't normative, it's just an unprincipled dumping ground for random bits of syntax and semantics and probably should have been deleted years ago, or at least renamed to something with less authoritative weight than "reference" to avoid misleading people as it often does. The Rust devs absolutely do want to thoroughly specify the language someday, though the immediate priority is making sure that Rust survives its first ten years.
- steveklabnik 8y ago
  > it's just an unprincipled dumping ground This is not the case, and I don't appreciate you disparaging others' hard work like this. The reference is accurate, but not complete. Anything inaccurate is a bug, and if they're found, we fix them like any other.
  - kibwen 8y ago
    > > it's just an unprincipled dumping ground > This is not the case, and I don't appreciate you disparaging others' hard work like this. It is the minimally-charitable interpretation of my statement to assume that I'm trying to disparage the people behind the reference. The document itself is lacking, which is a statement we can make about many nightly/unstable things without disparaging the people working on them; exacerbated in this case because the reference ships as part of the stable documentation, which implies a degree of quality that it does not yet live up to, especially given the high expectations that people have when they of a language reference document such as ECMAScript's or ISO C++. Starting from the first page of the reference, Notation: https://doc.rust-lang.org/stable/reference/notation.html https://doc.rust-lang.org/stable/reference/notation.html The first paragraph links to a section on special Unicode productions. This section defines identifiers in terms of Unicode's XID_start and XID_continue, but this is referring to the unstable non_ascii_idents feature, not anything in the stable language. There is a footnote noting as such, and saying that the situation is expected to improve soon, but this feature gate has existed since before 1.0 and AFAIK no RFC has ever been written to describe this feature, so this footnote gives a false sense of optimism. Furthermore, as per the discussion at https://github.com/rust-lang/rust/issues/28979 https://github.com/rust-lang/rust/issues/28979 , it's very unclear whether or not the stable form of this feature will end up using XID_start or XID_continue. My fix is https://github.com/rust-lang/rust/pull/50790 https://github.com/rust-lang/rust/pull/50790. In the same section on Special Unicode Productions, it defines the non_null character class as any Unicode character but null, and then the non_eol character class as any non_null character except for newline. Below it then defines a grammar for line comments as two forward-slashes followed by zero or more non_eol characters. But this is incorrect, because Rust does allow null characters in comments: I don't expect that a code example will survive network transmission, but modify the following program by replacing $ with a null to see that it only prints "2", not "1\n2": fn main() { // test $ println!("1"); println!("2"); } I doubt that this is a bug in rustc, because Go, which like Rust also mandates UTF-8 source files, considers newline to be the only way to terminate a line comment and AFAIK has no issues with accepting nulls. We also allow other nonprinting characters in comments. This same error exists for the classes concerning what is valid in char and string literals. My fix is https://github.com/rust-lang/rust/pull/50791 https://github.com/rust-lang/rust/pull/50791. Going back to the Notation page, the next paragraph has links to the sections on unary and binary operators. The section on the dereference operator has a typo: "variance" should be "variable". The section on the question mark operator has the typo "errornous". The operator table should have a footnote specifying that integer division rounds toward zero (as opposed to applying a floor function, e.g. http://mathworld.wolfram.com/IntegerDivision.html http://mathworld.wolfram.com/IntegerDivision.html). (Given the existing footnotes specifying the behavior of the right-shift operator, I assume this is the proper place for this.) Further down, the section on type casts is incomplete; the coercion table misses that non-capturing closures can be cast to function pointers. The section on assignment expressions should note that assignment expressions evaluate to (). Fixes at https://github.com/rust-lang-nursery/reference/pull/337 https://github.com/rust-lang-nursery/reference/pull/337. The Notations page links to a section on tokens. The Characters and strings table has a column labeled "# sets" that uses notation like "0...", which should have a footnote for clarification. The section on Character escapes refers to the previously-defined term "7-bit character code" as an "8-bit code point escape". In the section on Byte and byte string literals, the grammar definitions for ASCII_FOR_CHAR and ASCII_FOR_STRING exclude forward slashes, when they should exclude backslashes. The section on invalid integer literals says that overflowing literals are invalid, but they're not (this one is arguably something that ought to be changed, and I've opened https://github.com/rust-lang/rfcs/pull/2438 https://github.com/rust-lang/rfcs/pull/2438 to discuss changing it). The section on valid integer suffixes omits the new 128-bit types. Fixes at https://github.com/rust-lang-nursery/reference/pull/338 https://github.com/rust-lang-nursery/reference/pull/338 for these. That covers all pages reachable from the first two paragraphs of the reference and notes all the errors that are obvious to me in a single pass. I don't intend this as a disparagement of the documenters--language references are damn hard. There's surely plenty that I've overlooked. The degree of detail is overwhelming and the inherent authority of the word "reference" means that stakes are high. Compared to our other stellar docs the reference is notably lacking, and releasing it alongside them is an outlier from our usual standard of quality. Several large concepts are missing (such as, AFAICT, the type inference algorithm); the section on unsafety may even (if I'm properly interpreting the mood of the members of the unsafe code guidelines working group) be verging on misleadingly dangerous (suffice to say I think the Nomicon should be nightly-only as well (which is also not intended as a disparagement of Gankro's efforts)). The fact that people are still interpreting the reference so authoritatively suggests that more steps could be taken to reduce confusion. At the very least I think it should moved to nightly-only (and likewise remove its mention from www.rust-lang.org)... and maybe also add one of these: http://images.mentalfloss.com/sites/default/files/styles/insert_main_wide_image/public/under%20construction1_0.gif http://images.mentalfloss.com/sites/default/files/styles/ins... :) I apologize for the phrase "unprincipled dumping ground", it was a rash way of saying that the reference is developed in an ad-hoc way where sections are (mostly) added or improved without apparent overarching guidance or large-scale vision, hence all the missing pieces and parts that still date back to 1.0. I also apologize for suggesting that it ought to have been deleted; I still harbor a latent prejudice against the reference for all the years where it existed without anybody noticing that multiplication's precedence was specified as somewhere between addition and subtraction. :)

steveklabnik 8y ago

This is because this aspect of Rust is simply not yet defined. There are people working on it. Once it's agreed upon, it will be well-documented. Outside of the memory model, there's been a few people putting a lot of work into the reference lately; it's been growing a lot. It's a tricky problem.

mjw1007 8y ago
That's perhaps an excuse for having imperfect documentation. I don't think it's an excuse for it being in the state it's currently in. Have you looked at that chapter recently? It starts by saying « A Rust program's memory consists of a static set of items and a heap », and literally two sentences later it's talking about «the stack» as if the reader is supposed to know what that is (and as if there's only one stack).
- steveklabnik 8y ago
  Sure. Please file bugs about stuff like this: https://github.com/rust-lang-nursery/reference/issues/new https://github.com/rust-lang-nursery/reference/issues/new That section of the reference is basically inherited from the very old days. Most of the work has been focused on the other parts. Sometimes it takes an outside perspective to notice these kinds of things. I appreciate you bringing it up. Filing a bug means that it won't get lost. If you don't want to, then I'm happy to on your behalf.

kibwen 8y ago

The Rust memory model is basically "the C11 memory model, except static checks prevent the unsound parts". We don't have much of a choice, given that we basically pretend to be C at the LLVM IR level and that we want to heavily leverage LLVM's existing optimization passes, which were designed with C in mind. The "reference" isn't normative, it's just an unprincipled dumping ground for random bits of syntax and semantics and probably should have been deleted years ago, or at least renamed to something with less authoritative weight than "reference" to avoid misleading people as it often does. The Rust devs absolutely do want to thoroughly specify the language someday, though the immediate priority is making sure that Rust survives its first ten years.

steveklabnik 8y ago
> it's just an unprincipled dumping ground This is not the case, and I don't appreciate you disparaging others' hard work like this. The reference is accurate, but not complete. Anything inaccurate is a bug, and if they're found, we fix them like any other.
- kibwen 8y ago
  > > it's just an unprincipled dumping ground > This is not the case, and I don't appreciate you disparaging others' hard work like this. It is the minimally-charitable interpretation of my statement to assume that I'm trying to disparage the people behind the reference. The document itself is lacking, which is a statement we can make about many nightly/unstable things without disparaging the people working on them; exacerbated in this case because the reference ships as part of the stable documentation, which implies a degree of quality that it does not yet live up to, especially given the high expectations that people have when they of a language reference document such as ECMAScript's or ISO C++. Starting from the first page of the reference, Notation: https://doc.rust-lang.org/stable/reference/notation.html https://doc.rust-lang.org/stable/reference/notation.html The first paragraph links to a section on special Unicode productions. This section defines identifiers in terms of Unicode's XID_start and XID_continue, but this is referring to the unstable non_ascii_idents feature, not anything in the stable language. There is a footnote noting as such, and saying that the situation is expected to improve soon, but this feature gate has existed since before 1.0 and AFAIK no RFC has ever been written to describe this feature, so this footnote gives a false sense of optimism. Furthermore, as per the discussion at https://github.com/rust-lang/rust/issues/28979 https://github.com/rust-lang/rust/issues/28979 , it's very unclear whether or not the stable form of this feature will end up using XID_start or XID_continue. My fix is https://github.com/rust-lang/rust/pull/50790 https://github.com/rust-lang/rust/pull/50790. In the same section on Special Unicode Productions, it defines the non_null character class as any Unicode character but null, and then the non_eol character class as any non_null character except for newline. Below it then defines a grammar for line comments as two forward-slashes followed by zero or more non_eol characters. But this is incorrect, because Rust does allow null characters in comments: I don't expect that a code example will survive network transmission, but modify the following program by replacing $ with a null to see that it only prints "2", not "1\n2": fn main() { // test $ println!("1"); println!("2"); } I doubt that this is a bug in rustc, because Go, which like Rust also mandates UTF-8 source files, considers newline to be the only way to terminate a line comment and AFAIK has no issues with accepting nulls. We also allow other nonprinting characters in comments. This same error exists for the classes concerning what is valid in char and string literals. My fix is https://github.com/rust-lang/rust/pull/50791 https://github.com/rust-lang/rust/pull/50791. Going back to the Notation page, the next paragraph has links to the sections on unary and binary operators. The section on the dereference operator has a typo: "variance" should be "variable". The section on the question mark operator has the typo "errornous". The operator table should have a footnote specifying that integer division rounds toward zero (as opposed to applying a floor function, e.g. http://mathworld.wolfram.com/IntegerDivision.html http://mathworld.wolfram.com/IntegerDivision.html). (Given the existing footnotes specifying the behavior of the right-shift operator, I assume this is the proper place for this.) Further down, the section on type casts is incomplete; the coercion table misses that non-capturing closures can be cast to function pointers. The section on assignment expressions should note that assignment expressions evaluate to (). Fixes at https://github.com/rust-lang-nursery/reference/pull/337 https://github.com/rust-lang-nursery/reference/pull/337. The Notations page links to a section on tokens. The Characters and strings table has a column labeled "# sets" that uses notation like "0...", which should have a footnote for clarification. The section on Character escapes refers to the previously-defined term "7-bit character code" as an "8-bit code point escape". In the section on Byte and byte string literals, the grammar definitions for ASCII_FOR_CHAR and ASCII_FOR_STRING exclude forward slashes, when they should exclude backslashes. The section on invalid integer literals says that overflowing literals are invalid, but they're not (this one is arguably something that ought to be changed, and I've opened https://github.com/rust-lang/rfcs/pull/2438 https://github.com/rust-lang/rfcs/pull/2438 to discuss changing it). The section on valid integer suffixes omits the new 128-bit types. Fixes at https://github.com/rust-lang-nursery/reference/pull/338 https://github.com/rust-lang-nursery/reference/pull/338 for these. That covers all pages reachable from the first two paragraphs of the reference and notes all the errors that are obvious to me in a single pass. I don't intend this as a disparagement of the documenters--language references are damn hard. There's surely plenty that I've overlooked. The degree of detail is overwhelming and the inherent authority of the word "reference" means that stakes are high. Compared to our other stellar docs the reference is notably lacking, and releasing it alongside them is an outlier from our usual standard of quality. Several large concepts are missing (such as, AFAICT, the type inference algorithm); the section on unsafety may even (if I'm properly interpreting the mood of the members of the unsafe code guidelines working group) be verging on misleadingly dangerous (suffice to say I think the Nomicon should be nightly-only as well (which is also not intended as a disparagement of Gankro's efforts)). The fact that people are still interpreting the reference so authoritatively suggests that more steps could be taken to reduce confusion. At the very least I think it should moved to nightly-only (and likewise remove its mention from www.rust-lang.org)... and maybe also add one of these: http://images.mentalfloss.com/sites/default/files/styles/insert_main_wide_image/public/under%20construction1_0.gif http://images.mentalfloss.com/sites/default/files/styles/ins... :) I apologize for the phrase "unprincipled dumping ground", it was a rash way of saying that the reference is developed in an ad-hoc way where sections are (mostly) added or improved without apparent overarching guidance or large-scale vision, hence all the missing pieces and parts that still date back to 1.0. I also apologize for suggesting that it ought to have been deleted; I still harbor a latent prejudice against the reference for all the years where it existed without anybody noticing that multiplication's precedence was specified as somewhere between addition and subtraction. :)