Where in the docs is it?


#1

Is there a reference that goes into “all” the details about the core Rust language? For example, the “if” expression.

Some “if” information is in the first edition of The Book. Overlapping, but different information is found in the second edition. Rust by example shows examples of “if” in one place and “if let” in another place, but doesn’t discuss or explain it at all! The standard library API reference doesn’t have an entry for “if”, and neither does the Rustnomicon (that I can find).

I’m writing an Intro to Rust talk for OpenWest, and since I have to explain things like control flow, I would like to make sure to understand them in depth. But I’m having a hard time finding the “depth” in the documentation, even after combing over all the different types of docs!

Do the “while” and “for” loops have a “finally” clause? Can a “for” loop be annotated with a loop label? What other features and behaviors have I not even thought to look for? How do I research stuff at this level?

I feel like for the core language, Rust only has tutorials…and source code, with a big gaping hole in between. But I’m hoping I am just missing a documentation source somewhere.


#2

The closest thing is probably The Rust Reference, its if expression section is a bit bare bones but it appears to pretty much cover how the expression works. It also appears to answer your sample questions (while loops do not have finally clauses, for loops can have a label, you likely haven’t thought to look for the #[no_link] attribute which allows you to just use macros from a crate without actually linking the crate in).


#3

Thank you! I completely missed the Statements and Expressions chapter in the reference, which pretty much covers all the core language stuff.

Edit: Upon more careful reading of the reference, the densely packed text in it pretty much covers the details I was looking for. As long as I can safely assume that features not mentioned do not exist, then that’s pretty much exactly what I was missing. Thanks!


#4

Unfortunately this is not the case for the reference in general: It lagged behind the language for quite a while, and is still incomplete in many areas. Some people are working on bringing it up-to-date, and there’s a new process in place to ensure new features get documented before they ship.

In the specific cases of if and for expressions, I don’t see any syntax omitted, though the descriptions of their semantics could certainly be more detailed…


#5

Oh! That’s sorta scary :frowning:

I’ll just give it my best with the docs I have, then.


#6

You can find exact details about many language features in the RFCs that introduces them (“Detailed design” section).


#7

So, is the best way to do that to clone the RFC repo and grep through this directory?


#8

Github search usually works quite well.


#9

The project to update the reference with all the rfcs is at:

If you come across anything that can be explained better, Please pr!
Eavan a pr that adds this is out of date see rfc ### for the new approach. Would help.


#10

Thank you!