[Gankra]

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/

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]

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/

(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]

> 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.

[Sharlin]

I don't think Gankra is confusing them as much as asserting that a full specification should almost never be required reading for a user of a language, just like you don't need the detailed blueprints of a building to live or work there, or even to do simple repairs or redecoration.

A detailed specification only matters if you're trying to construct another building to the same spec (write another compiler), want to do heavy renovation work (implement a major new feature on rustc), or if the technical details are insufficiently "abstracted out" (say, there are exposed live wires that you have to know to avoid in daily use – cf. undefined behavior in C and C++).

[simplotek]

> I don't think Gankra is confusing them as much as asserting that a full specification should almost never be required reading for a user of a language (...)

My point is that this line of argument makes no sense.

It's like claiming that dictionaries and English grammar books are not needed because kids learning their ABCs almost never require reading those to learn how to speak English.

Rust standardization opponents insist in these moot strawmen arguments. They completely miss the whole point of a standard. Standards are critical because how things work need to be specified in precise terms that are set in stone. Standards are read to gain deeper understanding of a language. They are used to clarify corner cases and obscure issues and behavior. You do not need a ISO standard because you want to write a "hello world". You need an ISO standard because you are a mature professional that understands that "it works on my machine" is not an acceptable answer to any question you have on how a programming language supposedly works.

[tialaramex]

> It's like claiming that dictionaries and English grammar books are not needed because kids learning their ABCs almost never require reading those to learn how to speak English.

I don't think this makes the case you were hoping for?

Both Dictionaries and actual "English grammar books" (not pedantry written by non-experts like Lynne Truss) are descriptive because English is a natural language. I don't own the full Cambridge Grammar of the English Language but here's an extract from the Student's Introduction which I do own. (The Introduction is intended to be suitable as an undergraduate text)

"... it isn't sensible to call a construction grammatically incorrect when people whose status as fully competent speakers of the standard language is unassailable use it nearly all the time".

We don't use these books to teach children or ESL (English as a 2nd language) learners. My employer runs "pre-sessionals" which are short language courses for overseas students, they have a conditional visa, they fly in a month or two before term starts and they take our intensive ESL courses, if they do OK they're signed off as able to successfully use English, they start their degree course (say, Electronics) and the visa conditions check off, if they can't hack it the visa conditions terminate their stay and they are sent back. This allows us to recruit foreign students who could, if they apply themselves, be successful - without them needing to somehow find local English tutors in their home country, squeeze in learning a foreign language and convince immigration they've learned enough English to follow their degree course.

It is not the goal of pre-sessionals to teach a Chinese teenager to say "It is I" rather than "It's me" because that's a weird hyper-formal English. It is the goal that they should understand phrases their tutors and peers might use, which are often going to be informal or even somewhat non-standard, and be able to express themselves in both formal and informal contexts. They should be able to read say an Economist article, write a 1000 word summary of the article and talk about it in conversation.

Books like CGEL and dictionaries represent our understanding of how a very complicated system is actually used by real people. They are not guides to how English should work, such a document would be very silly.

> Standards are critical because how things work need to be specified in precise terms that are set in stone.

This is a mythologized version of what's going on. If a language is spending huge amounts of money and personal effort on the ISO process I can understand they'd want to project this myth, but it isn't true.

For C++ in particular - the most obvious comparison from the ISO standard languages to Rust - huge swathes of important stuff is "ill-formed, no diagnostic required" in the standard. If your C++ program falls foul of any such clauses, anywhere, even once in some obscure sub-routine you don't use, too bad your entire C++ program has no defined meaning and the compiler is not expected to report this as an error or warn you about the trouble you're in.

Let's use my favourite modern example. Suppose we've got a std::vector of float, and we sort that using std::sort but in some cases, due to an oversight, one element of the vector can be NaN. In C++ 20 Our entire program is undefined and anything might happen because of clauses introduced by the C++ 20 Concepts feature. Our program probably works fine in practice, but no thanks to your "critical" standard.

[torstenvl]

> Rust is extremely tuned for "fuck around and find out"

Yes. And the issue is, that's not an acceptable stance for a language seeking to be a systems programming language.

[Gwypaas]

If what you've created is unsound, then that is a compiler bug. Or you depend on something using unsafe which is unsound. Therefore you should, in both cases, appropriately report it.

[torstenvl]

There is literally no such thing as a compiler bug in a language defined by "whatever the compiler does." The compiler is always, tautologically, correct.

[GolDDranks]

You are being pedantic here; this stance doesn't survive contact with the real world. The fact that Rust's language reference is not complete/up to date, doesn't mean that Rust is defined _just_ by "whatever the compiler does." There are community-wide accepted documents (the reference, Rustonomicon, RFCs, and more informally, Language/Compiler team meeting notes/comments that reflect their consensus about the semantics) how Rust _ought_ to work.

[tga_d]

By that reasoning specifications can't have bugs either. Sure, by some extreme prescriptive understanding of what a compiler or specification is, there are no bugs, but if a cryptography specification allows attacks in the threat model or rustc segfaults, all but the most asinine parties would agree there's a bug -- what's the point of asserting otherwise?