6 ms·

I don't think people who are asking for an accurate description of Rust are holding it to a higher standard than other languages. Rust's current reference docs

I don't think people who are asking for an accurate description of Rust are holding it to a higher standard than other languages. Rust's current reference docs, more than seven years after Rust 1.0 was released, are much weaker than the first version of the Java specification (which was published seven _months_ after JDK 1.0). The place where it seems to me that there's a strange inconsistency is inside the Rust community: when discussing package management or compiler error messages or tutorial documentation or pretty much anything else I can think of, the there seems to be general agreement that Rust should aim to be best in class. But when it comes to complete-and-correct documentation, I hear voices saying "are we sure we need this?", and "we're no worse than C was in 1985", and "we shouldn't let writing documentation slow down releasing new features".

tialaramex 4y ago
> But when it comes to complete-and-correct documentation, I hear voices saying "are we sure we need this?", and "we're no worse than C was in 1985", and "we shouldn't let writing documentation slow down releasing new features". Topic matters. Take the Guaranteed Niche Optimisation. Many users rely on Rust's promise that Option<&T> is the same size as &T for example, that's the "Guaranteed Niche Optimisation" (the niche in &T is that it can't be a NULL pointer) If the specification didn't mention this at all, or said eh, we can't promise anything, that would be a problem. I've no doubt serious Rust users would demand this get written down properly. But the exact details of the Guarantee aren't so important. Far more people care that Option<&T> is the same size as &T, than care about, say, Option<NonZeroU32> let alone more obscure types that are in practice optimised. If it turned out the guarantee was narrower than you expected, but only for some type you never use, is that important? What if Option<Infallible> wasn't a ZST due to a compiler bug? I'd guess Rust internal tests would notice, but if not I'm not sure how much real software would care. If somebody can spend next week either carefully documenting exactly what the Guaranteed Niche Optimisation is, all the fine details, or implementing a cute niche optimiser trick which turns out to make the most popular JSON parser use 1% less RAM and 5% less CPU, the latter is just clearly the better deal.
- mjw1007 4y ago
  From where I stand, this is just one more example of members of the Rust community working hard to find excuses for not having documentation. To the extent that people are relying on the common cases of the niche optimisation taking place: yes, the Rust description should be documenting what people may rely on, and should have been documenting it for years. In order to do that there's absolutely no need to describe the fine details of exactly where the optimisation currently applies.
  - Gankra 4y ago
    The null pointer optimization is documented in many places, here's one official instance I published in 2015: https://doc.rust-lang.org/nomicon/repr-rust.html https://doc.rust-lang.org/nomicon/repr-rust.html There are many random details of a language that are "important" and they get documented all over the place. If it was all under "THE REFERENCE" and was a 500 page PDF, would the information actually be more discoverable? How would you even know to look up what you don't know? Are you going to read the reference cover to cover before writing hello world?
    - mjw1007 4y ago
      If the people maintaining a language produce a complete and correct description, then thousands of other people around the world can use it to provide helpful and correct blog posts, Stack Overflow answers, and so on. But those thousands of people, however enthusiastic, can't produce authoritative documentation, because that needs the maintainers' "sign-off".
- scoutt 4y ago
  > What if Option<Infallible> wasn't a ZST due to a compiler bug? ... I'm not sure how much real software would care. I'm speaking out of ignorance here but, is there a chance of overflowing the stack of a small microcontroller even by one byte with this? Or other side effects on platforms that are not even remotely capable of parsing JSON? If that's the case and my ECU crashes and people die, should I rely on the fact that an user on Github promised me that the code generated should be correct? Who ensures this? Under these conditions, how Ferrocene or the next Greenhills can achieve certifications? Shouldn't be an authoritative document that says "'this thing' must have 'this size'", or "depends on implementation", "depends on platform" or even "behavior is undefined"?
Gankra 4y ago
I am one of the people who has written a lot of Rust's docs, including one of the early attempts at "specifying" details of the language: the Rustonomicon. Rust's documentation is taken very seriously and often praised! But we focus on documenting actual APIs (with examples that we actually run in CI to make sure they don't break!) (and links to the actual implementation to dig deeper!). We also gave everyone builtin tools to write their own docs to the same standard and automatically build and host them. Example: https://docs.rs/tracing/0.1.37/tracing/ https://docs.rs/tracing/0.1.37/tracing/ What Rust has eternally lagged on is properly documenting little fiddly nubs like "this is an integer literal expression which decays..." and "the grammar for a pattern expression is...". For whatever reason some people think these details are of THE UTMOST IMPORTANCE, instead of just being a thing you try out and see what happens. Or a thing you discover by reading existing code, books, examples, posts, etc. As a language Rust is extremely tuned for "fuck around and find out". I can rattle off some spooky interactions in Rust but I always end up concluding with "... and in practice this doesn't really matter because if you run afoul of it you just get a compilation error (or a lint)". In this regard knowing fiddly details about Rust... tends to not matter. Unless you're writing Unsafe Code. Then you read the book I wrote, and eventually you drill down the rabbit hole deep enough to learn that "oh actually C doesn't even know what this means. UHHH... WELL. FINE?"
- mjw1007 4y ago
  I agree entirely with you that Rust, today, is well-adapted to people who like to learn by the "fuck around and find out" route. But it often feels as if the Rust community doesn't believe that people who prefer to learn by reading accurate documentation exist. I commend the following page to you to get an idea of the mindset involved: https://blog.nelhage.com/post/computers-can-be-understood/ https://blog.nelhage.com/post/computers-can-be-understood/ (No doubt it will gladden your heart to know that I updated the Reference to document the somewhat surprising ways in which integer literal expressions decay earlier this year.)
- simplotek 4y ago
  > Rust's documentation is taken very seriously and often praised! But we focus on documenting actual APIs (with examples that we actually run in CI to make sure they don't break!) (and links to the actual implementation to dig deeper!). Your confusing two radically different types of documentation. Specifications, such as the ISO standards for C and C++, are the source of truth of what determines what the language actually is. Writing tutorials with example code ran in some implementation might help people onboard onto it but it does not, in any way, shape, or form, specify what's the language. It's like comparing blueprints of a construction site with random videos and photos of the same building.
duped 4y ago
I think that's a fair criticism of documentation of the language itself, for which there is no real documentation - while std/core is extensively documented and it is quite good, syntax/semantics of Rust are not outside of the Book, various RFCs and discussion related to them, and various online sources. But that's not what a language specification looks like. You will rarely turn to the ISO spec of C or C++ to learn something about the language unless you are trying to build a greenfield compiler. And while a lot of people want a second implementation of Rust for technical reasons, it's not as compelling as improving language documentation. For example language documentation would look like: the `for x in y {}` syntax is called a "for" loop, which iterates over the expression `y` by calling the `next` method until it returns `None`. (this is bad, but you get the idea) Language specification would be something like `for x in y { body }` is equivalent to let y = y.into_iter(); loop { match y.next() { Some(x) => { body }, None => break; } } While that language might be useful for some users, it's primarily useful for compiler developers. And since there is only one compiler, a spec to that detail is not compelling.
- cyber_kinetist 4y ago
  A counterpoint: I often found cppreference.com very useful when ironing out parts of C++ that I’m not sure about. (Yeah it’s not the full spec, but it’s at least a concise version of it made to be understandable for mortals.) Although the language has many cases of undefined behavior, at least they are clearly written down. Sucks to figure out how these rules all interact with each other though. Meanwhile, for unsafe Rust, if you look at the Rust Reference Book, there is a single page that lists the possible situations for undefined behavior, with an added warning message: “Warning: The following list is not exhaustive. There is no formal model of Rust's semantics for what is and is not allowed in unsafe code, so there may be more behavior considered unsafe. The following list is just what we know for sure is undefined behavior. Please read the Rustonomicon before writing unsafe code.” Then when I look at the Rustonomicon, it says: “Warning: This book is incomplete. Documenting everything and rewriting outdated parts take a while. See the issue tracker to check what's missing/outdated, and if there are any mistakes or ideas that haven't been reported, feel free to open a new issue there.” So maybe that should be more prioritized if Rust really wants to get the reputation of a safe, stable language. (Safe Rust is good, but Unsafe is where the real devils are all hidden…)

tialaramex 4y ago

> But when it comes to complete-and-correct documentation, I hear voices saying "are we sure we need this?", and "we're no worse than C was in 1985", and "we shouldn't let writing documentation slow down releasing new features". Topic matters. Take the Guaranteed Niche Optimisation. Many users rely on Rust's promise that Option<&T> is the same size as &T for example, that's the "Guaranteed Niche Optimisation" (the niche in &T is that it can't be a NULL pointer) If the specification didn't mention this at all, or said eh, we can't promise anything, that would be a problem. I've no doubt serious Rust users would demand this get written down properly. But the exact details of the Guarantee aren't so important. Far more people care that Option<&T> is the same size as &T, than care about, say, Option<NonZeroU32> let alone more obscure types that are in practice optimised. If it turned out the guarantee was narrower than you expected, but only for some type you never use, is that important? What if Option<Infallible> wasn't a ZST due to a compiler bug? I'd guess Rust internal tests would notice, but if not I'm not sure how much real software would care. If somebody can spend next week either carefully documenting exactly what the Guaranteed Niche Optimisation is, all the fine details, or implementing a cute niche optimiser trick which turns out to make the most popular JSON parser use 1% less RAM and 5% less CPU, the latter is just clearly the better deal.

mjw1007 4y ago
From where I stand, this is just one more example of members of the Rust community working hard to find excuses for not having documentation. To the extent that people are relying on the common cases of the niche optimisation taking place: yes, the Rust description should be documenting what people may rely on, and should have been documenting it for years. In order to do that there's absolutely no need to describe the fine details of exactly where the optimisation currently applies.
- Gankra 4y ago
  The null pointer optimization is documented in many places, here's one official instance I published in 2015: https://doc.rust-lang.org/nomicon/repr-rust.html https://doc.rust-lang.org/nomicon/repr-rust.html There are many random details of a language that are "important" and they get documented all over the place. If it was all under "THE REFERENCE" and was a 500 page PDF, would the information actually be more discoverable? How would you even know to look up what you don't know? Are you going to read the reference cover to cover before writing hello world?
  - mjw1007 4y ago
    If the people maintaining a language produce a complete and correct description, then thousands of other people around the world can use it to provide helpful and correct blog posts, Stack Overflow answers, and so on. But those thousands of people, however enthusiastic, can't produce authoritative documentation, because that needs the maintainers' "sign-off".
scoutt 4y ago
> What if Option<Infallible> wasn't a ZST due to a compiler bug? ... I'm not sure how much real software would care. I'm speaking out of ignorance here but, is there a chance of overflowing the stack of a small microcontroller even by one byte with this? Or other side effects on platforms that are not even remotely capable of parsing JSON? If that's the case and my ECU crashes and people die, should I rely on the fact that an user on Github promised me that the code generated should be correct? Who ensures this? Under these conditions, how Ferrocene or the next Greenhills can achieve certifications? Shouldn't be an authoritative document that says "'this thing' must have 'this size'", or "depends on implementation", "depends on platform" or even "behavior is undefined"?

Gankra 4y ago

I am one of the people who has written a lot of Rust's docs, including one of the early attempts at "specifying" details of the language: the Rustonomicon. Rust's documentation is taken very seriously and often praised! But we focus on documenting actual APIs (with examples that we actually run in CI to make sure they don't break!) (and links to the actual implementation to dig deeper!). We also gave everyone builtin tools to write their own docs to the same standard and automatically build and host them. Example: https://docs.rs/tracing/0.1.37/tracing/ https://docs.rs/tracing/0.1.37/tracing/ What Rust has eternally lagged on is properly documenting little fiddly nubs like "this is an integer literal expression which decays..." and "the grammar for a pattern expression is...". For whatever reason some people think these details are of THE UTMOST IMPORTANCE, instead of just being a thing you try out and see what happens. Or a thing you discover by reading existing code, books, examples, posts, etc. As a language Rust is extremely tuned for "fuck around and find out". I can rattle off some spooky interactions in Rust but I always end up concluding with "... and in practice this doesn't really matter because if you run afoul of it you just get a compilation error (or a lint)". In this regard knowing fiddly details about Rust... tends to not matter. Unless you're writing Unsafe Code. Then you read the book I wrote, and eventually you drill down the rabbit hole deep enough to learn that "oh actually C doesn't even know what this means. UHHH... WELL. FINE?"

mjw1007 4y ago
I agree entirely with you that Rust, today, is well-adapted to people who like to learn by the "fuck around and find out" route. But it often feels as if the Rust community doesn't believe that people who prefer to learn by reading accurate documentation exist. I commend the following page to you to get an idea of the mindset involved: https://blog.nelhage.com/post/computers-can-be-understood/ https://blog.nelhage.com/post/computers-can-be-understood/ (No doubt it will gladden your heart to know that I updated the Reference to document the somewhat surprising ways in which integer literal expressions decay earlier this year.)
simplotek 4y ago
> Rust's documentation is taken very seriously and often praised! But we focus on documenting actual APIs (with examples that we actually run in CI to make sure they don't break!) (and links to the actual implementation to dig deeper!). Your confusing two radically different types of documentation. Specifications, such as the ISO standards for C and C++, are the source of truth of what determines what the language actually is. Writing tutorials with example code ran in some implementation might help people onboard onto it but it does not, in any way, shape, or form, specify what's the language. It's like comparing blueprints of a construction site with random videos and photos of the same building.

duped 4y ago

I think that's a fair criticism of documentation of the language itself, for which there is no real documentation - while std/core is extensively documented and it is quite good, syntax/semantics of Rust are not outside of the Book, various RFCs and discussion related to them, and various online sources. But that's not what a language specification looks like. You will rarely turn to the ISO spec of C or C++ to learn something about the language unless you are trying to build a greenfield compiler. And while a lot of people want a second implementation of Rust for technical reasons, it's not as compelling as improving language documentation. For example language documentation would look like: the `for x in y {}` syntax is called a "for" loop, which iterates over the expression `y` by calling the `next` method until it returns `None`. (this is bad, but you get the idea) Language specification would be something like `for x in y { body }` is equivalent to let y = y.into_iter(); loop { match y.next() { Some(x) => { body }, None => break; } } While that language might be useful for some users, it's primarily useful for compiler developers. And since there is only one compiler, a spec to that detail is not compelling.

cyber_kinetist 4y ago
A counterpoint: I often found cppreference.com very useful when ironing out parts of C++ that I’m not sure about. (Yeah it’s not the full spec, but it’s at least a concise version of it made to be understandable for mortals.) Although the language has many cases of undefined behavior, at least they are clearly written down. Sucks to figure out how these rules all interact with each other though. Meanwhile, for unsafe Rust, if you look at the Rust Reference Book, there is a single page that lists the possible situations for undefined behavior, with an added warning message: “Warning: The following list is not exhaustive. There is no formal model of Rust's semantics for what is and is not allowed in unsafe code, so there may be more behavior considered unsafe. The following list is just what we know for sure is undefined behavior. Please read the Rustonomicon before writing unsafe code.” Then when I look at the Rustonomicon, it says: “Warning: This book is incomplete. Documenting everything and rewriting outdated parts take a while. See the issue tracker to check what's missing/outdated, and if there are any mistakes or ideas that haven't been reported, feel free to open a new issue there.” So maybe that should be more prioritized if Rust really wants to get the reputation of a safe, stable language. (Safe Rust is good, but Unsafe is where the real devils are all hidden…)