4 ms·
> 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 sh
by 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 agoFrom 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 agoThe 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 agoIf 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"?
- tialaramex 4y ago> is there a chance of overflowing the stack of a small microcontroller even by one byte with this? Maybe? If Option<Infallible> was mistakenly not a ZST I guess it might cost one byte to store the None/ Some discriminator (which would always be None in this example). > 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"? Well, wait, the current situation is that if the specification doesn't say, Rust isn't promising what size it is. It does say that Option<&T> is the same size as &T, and various other useful things, including an outline of the Guaranteed Niche Optimization, but there are definitely edge cases that are hard to reason about from the human text and it's reasonable to say these are not specified. I think if your ECU kills people if the size is wrong, you should probably have demanded more than "It wasn't clear in the specification so I asked on GitHub" and so should your regulator if you're in a regulated industry. If you're happy with "it depends" as an answer then congratulations, Rust can meet that today. But then it seems like you should be more careful with that ECU. I recommend adding hardware failsafe systems so that when, not if, you screw up, you don't kill anybody.
- scoutt 4y ago> Maybe? ... It does say that Option<&T> is the same size as &T.. but there are definitely edge cases If this is true then the spec should say "using Option<&T> in certain cases carries allocations of undefined size". Other than forcing me to not use Option<&T> in my embedded systems (which IIRC is widely used), what is the solution? MISRA Rust specs mandating "NO Option<&T>"? Saying "You used Option<&T> with an edge case. The compiler is not consistent with edge cases sometimes. Don't do that" is shifting the blame on the programmer once again and this is bad for Rust for the reasons everybody knows. Or I am misintepreting "edge cases that are hard to reason about from the human text". > you should probably have demanded more Demanded who? how? See how difficult is to integrate Rust in an automotive/industrial company like the one I work for? Who should I sue if I found code generated "out of specs" (specs which don't exist in the first place)? > ... and so should your regulator if you're in a regulated industry. But this can't happen right now. I guess regulators will want to rely on ISO or other formal specs for language specifications. And where is this so-called specification? Do you have a link? Where can I get a hard copy? Is it this? https://doc.rust-lang.org/reference/ https://doc.rust-lang.org/reference/