Thanks For Asking!

16 August 2018

One part of my personal dedication to Rust is writing weekly “Ask easy questions here” threads on the rust subreddit. One thing that recently occurred to me is that most of the questions asked may hint at a deficiency in documentation and teaching material. We are, as far as I know, not using this resource for now.

So here’s a broad categorization of the topics of the last three weeks’ worth of questions:

questions about the new edition, or other new / unstable features. Those are to be expected and usually come from early adopters which accept missing documentation

people asking for code review. Interestingly I haven’t seen request for mentors yet

misleading or hard to interpret error messages – those are usually followed up with a rust issue. Though there is still work to be done, all is well in that regard

generics, where clauses, associated types (especially the <Foo as Bar>::Baz syntax), coherence and trait object safety

syntax), coherence and trait object safety lifetime issues, we still haven’t found an easy way to teach them, so people are going through some pain here. On the other hand, most such questions get quite great answers, which we should probably mine for teaching approaches

macro_rules! definition and usage – though DanielKeep’s little book of rust macros is a great resource, either it is insufficiently advertised, or we need to come up with other documentation

definition and usage – though DanielKeep’s little book of rust macros is a great resource, either it is insufficiently advertised, or we need to come up with other documentation error handling: ? operator, Error type translation, custom error types, the failure crate

operator, Error type translation, custom error types, the failure crate crate organization, subcrates and workspaces. I must admit that I don’t yet have a handle on how this stuff works, despite using it in three of my projects

the module system (“can main.rs use path/to/lib.rs , and if yes, how?”), how and why to use somecrate::prelude::* – this stuff is in flux and will probably be improved soon

use , and if yes, how?”), how and why to – this stuff is in flux and will probably be improved soon iterator usage: Perhaps the Iterator documentation could use more examples

documentation could use more examples data strucure pragmatics and usage

allocation, Box , the distinction between owned and borrowed values

, the distinction between owned and borrowed values drop order, drop() and the significance of the Drop trait

and the significance of the trait numeric casts and the non-availability of numeric inter-type operations (although the compiler messages have gotten very good by now)

blanket implementations of traits for arrays and tuples (those should probably have docstrings once #51885 is merged)

cross-compiling to non-standard targets (embedded, WASM or CUDA)

Hopefully someone interested in improving Rust’s learnability finds this useful.