Rust and Cargo documentation


#1

I am a retired computer professional, with degrees in physics and math. I have written software and run software projects for 50 years at places like BBN and MIT in everything from assembly language to Go and Haskell, with a lot of Lisp, Scheme, C, Tcl, and Python in the mix. My point is that I’m not a novice. Rust looks to me like a great concept. But … you knew there was a ‘but’ … the documentation, to which obvious effort has been devoted, is just not nearly good enough. For example, it is just about impossible to find how to get Cargo to link a given native library at a certain location. In other words, how to control the generated ld -l and -L options. There is much else that is like this, but it would be a major task in itself to write it all down.

I think the people who devote themselves to documenting Rust need to look at how both Go and Haskell have been documented. Neither are small, simple languages, especially not Haskell, that could be fully documented with a slim volume like K&R. And yet they both can be learned without undue frustration, because you can find what you need to know. I cannot say the same of Rust. I am repeatedly stymied by either not being able to find the information I need or finding it written in a language that looks like English but is extremely difficult to understand. Paul Hudak’s not so “Gentle” introduction to Haskell was and is not a problem for me; the Rust documentation is.


#2

For example, it is just about impossible to find how to get Cargo to link a given native library at a certain location. In other words, how to control the generated ld -l and -L options.

Have you seen the build script docs, specifically http://doc.crates.io/build-script.html#outputs-of-the-build-script ?


#3

Are there pieces of Rust’s documentation that you can point to as being particularly difficult for you to understand? Alternatively, is there documentation for Go/Haskell that is particularly good at explaining something that ours is not?


#4

Part of the problem is just finding stuff. Another issue is the
quality of the writing.

On the former, I would cite the Index of the Python Library Reference
as something I have used repeatedly to find what I needed. Haskell
provides a similar index of its libraries (see
https://downloads.haskell.org/~ghc/7.6-latest/docs/html/libraries/index.html).
Both systems provide a Table of Contents and an index. Both are
needed. Rust does not provide the latter and it’s a real problem, in
my opinion.

As for the latter, an example is the section in the Book on References
and Borrowing, in the subsection ‘&mut references’. It is trying to
explain why the mutable borrow needs to be in a block, a restricted
scope, the reason being that ‘println!("{}", x);’ creates an immutable
borrow of ‘x’. Whoever wrote this didn’t think about the fact that
people are reading this because they don’t know Rust. Something that
looks like ‘x’ isn’t a borrow. We’ve been taught earlier that borrows
are references, pointers, and look like ‘&x’. So what the hell is
going on here? To understand this, you have to realize that

a. println! is a macro, not a function, the section on which appears
much later in the book, and
b. println!'s expansion contains an immutable borrow of ‘x’.

This one confused me for awhile, but I finally figured it out. I’ve
been doing this stuff for a long time, as I mentioned in my message.
What about someone who is relatively new to this game? I think they’d
be completely confused by this.This is just the tip of the iceberg.
When I found things confusing or obscure, I would search the web. Many
times I found people asking exactly the questions I had and I
repeatedly found the words “confused” or “can’t figure it out”, etc.
These are all signs of inadequate documentation.

I had no such issues in learning and using Go. I suggest you have a
look at how their documentation is organized and written.

I’m much more impressed with the ideas behind Rust and with its design
than I am with Go. But when I try to use it, my progress is much
slower and frustration level much higher than is normal with me when
learning a new language, which I’ve done many, many times. It’s not
the design of the language; it’s the documentation.


#5

Hi there, primary documentation author here.

I am sorry that you’re frustrated. It’s really, really difficult to document an entire programming language. I agree with you that there are a lot of tough spots. I think it’s important to understand the historical context of the book and the docs, generally: until May, everything in Rust was changing, all the time. I was/still am mostly just trying to keep up. With dozens of people working on the actual language, and me and a handful of other people working on docs, it’s hard.

The nice thing is, though, that now that that period of change has ended, things will gradually get better. As a clear example of this, last week I officially started revising the book into the actual form I want it to be in, rather than just whatever I could get done to the best of my ability before the deadline. I’m taking extra care to go even slower and explain things in more detail. I’m confident that we’ll get there; it’s just a lot of work. Haskell and Python have both had decades to do this job.

Thank you for caring about this.


#6

And thank you for the thoughtful response. I understand what you are up
against. I’ve written a personal financial management tool (Gnucash done
the right way, in my humble opinion :slight_smile: and I am working on documenting it
for release on github (and for my wife). This thing is not nearly as
complex as Rust, by several orders of magnitude and the thing that’s
holding up my release is the documentation. I’ve been managing my own
finances with this thing for several years now and it works. Explaining it
ain’t so easy.

As time permits (when I’m not working on my own document!), I will go back
to the Rust document and provide suggestions as they come up. I can’t use
the language right now for the reasons I’ve given, but if I can help you
get the documentation where it needs to be, I’m happy to do so.

By the way, the OpenBSD project is a paragon of virtue when it comes to
documentation. Their man pages are far better than Linux’s and, in general,
the system is better documented (the FAQ on their website is excellent). If
you don’t use the system (I’m typing at you from a machine using OpenBSD –
I use both it and Linux (Arch, and experimenting with Alpine), for
different reasons) you can find the man pages and FAQ on openbsd.org, to
get a sense of the clarity and directness of their writing style.

/Don Allen


#7

I’ve taken a Rust hiatus and just come back and am re-reading The Book. A very small suggestion: in Variable Bindings/Type Annotations, there is a sentence that reads “If it can figure out what the type of something is, Rust doesn’t require you to actually type it out…” I don’t think it’s a good idea to use the word “type” with two entirely different meanings in the same sentence, particularly in a section about types! My suggestion: “If it can figure
out what the type of something is, Rust doesn’t require you to specify the type explicitly.”


#8

Thanks! I agree. Would you mind opening up an issue so I don’t lose track fo this? Thanks!


#9

I have created an issue on github, “Problems with The Book, suggested
fixes #30880”.

In addition to the problem I mentioned in my 1/9 message (below), I’ve
added another to the main body of the issue entry: