
How to write documentation for a Rust crate - lukastyrychtr
https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate
======
zelphirkalt
Well, I guess the most important part of docs is ... examples! Give your users
examples, from which they can derive, how to use parts of your library. Those
examples also better be explained in natural language as well and not just
somewhere in a git repo, so that the user does not need to build a mental
model of the ideas of your library first, before being able to understand your
examples. Oh and did I mention diagrams would help? As a professional group,
we truly suck at documenting things properly.

Many people think, that docs are done once they auto-generated API docs from
source code. They are not. That's not something that deserves the name
"documentation". Auto-generated API docs are among the last things to turn to,
when there is nothing else around or when you already understood the ideas of
the library and only need to look up a name of something. That's not only true
for Rust, but also for other languages.

~~~
quietbritishjim
Examples are the most important part of you docs _sometimes_. There are at
least two reasons for visiting docs:

* Want to understand generally how to use a new concept, typically at the class level (or more trickily at the two-or-three-classes level), e.g. how do I create a thread?

* Already familiar with the concept but want to do something specific, typically at the method level, e.g. how to test whether a string starts with a particular prefix?

There was a good post on Hackers News a few months ago breaking down
documentation visitors into four categories, so there's at least two more.

I think examples are very important in the first case, typically you want an
example led-approach to explaining new concepts. But examples are a lot less
important for method-level questions, and are often (not always) totally
redundant if you have really clear and precise information about the method
and its parameters.

Edit: But just to be clear, I agree that examples are really important and you
should definitely put them in your docs (at the class level and above).

Edit 2: Here's the article [1] and HN dicussion [2]. In that terminology, I
was distinguishing "explanation" and "reference". The other two types are
"tutorial" and "how-to guide".

[1]
[https://web.archive.org/web/20200312211539/https://www.divio...](https://web.archive.org/web/20200312211539/https://www.divio.com/blog/documentation/)

[2]
[https://news.ycombinator.com/item?id=21289832](https://news.ycombinator.com/item?id=21289832)

------
dhruvdh
I don’t know why the experience for the current top commenter has been so
poor, but I absolutely love Rust docs, and it never takes me more than a few
seconds on the website to find what I am looking for. Perhaps navigating just
takes a little getting used to.

If something doesn’t make sense to me I can straight away jump into the source
code and make sense of it, from a single click.

I have learned so much about programming just reading the docs for the
standard library, or it’s source code. The documentation is one of my
favourite things about it the language.

~~~
OJFord
> I don’t know why the experience for the current top commenter

Meta: the experience for readers of your comment would be much better if you'd
chosen to _reply_ to that not-now-currently top commenter.

I think almost certainly it was this:
[https://news.ycombinator.com/item?id=22636726](https://news.ycombinator.com/item?id=22636726)

But that may not be clear at all to later readers if there are many comments
here.

------
jnordwick
Why does the rust documentation still suck? It basically only works if you
already know what you ate looking for, and still is difficult to read.

Compare the string pages.

Rust: [https://doc.rust-
lang.org/std/string/struct.String.html](https://doc.rust-
lang.org/std/string/struct.String.html)

Java:
[https://docs.oracle.com/en/java/javase/11/docs/api/java.base...](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html)

C++:
[https://en.cppreference.com/w/cpp/string/basic_string](https://en.cppreference.com/w/cpp/string/basic_string)

Yes, the cop page probably has some bespoke work on the page, but it still
demonstrates ideas that are partially auto generated (and most of that page is
auto generated).

* the method and functions aren't sectioned in any useful way. Just a list of functions (solved by adding section and subsection to the doc comments). Methods that create, search, mutate, test, transform, etc should be sectioned off.

* no use of alignment, just blobs of text

* poor use of color. Both java and cpp use color to break up sections and alignment to distinguish different parts of the signature. Rust is just a page of text that is very difficult to scan.

* no summary. Cpp summarizes the group of method before clicking b through to individual listings, while java summarizes each method at the top. This is useful for searching in a page. Rust is once again just a block of text.

* rust also has a unique issue in how to organize traits and other rust specific constructs. It really should have figured this out by now.

I can keep going on the uselessness of the rust docs, and I say this as
someone who was involved in the language in the past, and give it a new shot
about once a year. But the docs have always sucked compared to other
languages.

~~~
steveklabnik
So, I disagree that it "sucks," but what I will say is this: rustdoc has
basically been maintained by one or two people over the last ~5 years. It is
very hard to contribute to, because it has to use the compiler itself to
actually generate the documentation. This means that changing it means
changing the compiler, which means a long development cycle. Additionally,
this also means working on it isn't really like working on a normal web app.
We've tried to get folks to contribute, but they all bounce off. So this means
that any improvements we would like to do are really difficult, and there's
not a lot of help.

I am hoping that the rust-analyzer work lets us completely fix this, in the
same way I was hoping the rls would before, but it's just not ready yet.

~~~
jnordwick
> This means that changing it means changing the compiler,

Wow. What a terrible decision. I'm quite surprised that people actually agreed
to that.

I originally said it was shit but I toned it down a little. The information
isn't bad, just too difficult to find if you don't already know exactly what
you are looking for. You work on rust core so I don't think you are the best
person to judge.

The good part is this can mostly be solved by better formatting and adding a
top one-one summary section that groups similar functions and traits
(creation, mutation, lookup, etc). With just that you could even convince me
to ignore the terrible formatting in the lower section.

The general take away is that the docs are too difficult to scan and if you
don't already know something exists and its name, the docs aren't very useful.

~~~
steveklabnik
> Wow. What a terrible decision. I'm quite surprised that people actually
> agreed to that.

It's not really possible in any other way. Building API docs is a compilation
process, from source code to HTML. You either use the compiler, or re-
implement parts of it. The latter makes for interesting bug possibilities.

------
animalnewbie
I want to thank the rust team- they are extremely dedicated people taking care
of the smallest details and giving a compiler and related infrastructure for
free. Everyone on the team I've interacted with are amazingly kind and helpful
people.

I wish the Reddit community was less of a cancer but I guess it's not the team
that's responsible, and also it's reddit after all!

------
_bxg1
+1 to the code examples. Rust's type systems tells you a lot on its own about
what you can and cannot do, but it's often unclear as to what you _should_ do.
Which struct should I be starting with? Should I be constructing Foo directly
or though a utility function provided in a different module? Which of these
modules has what I need to do what I came here to do, as opposed to
advanced/optional features that most people won't care about?

Even just a single example of the most common use-case does wonders for
usability. Even if it's not quite what you need, it tells you about the
conventions and gives you things you can maybe swap out with other things in
the crate as needed.

------
joshmarlow
One of my personal pet peeves is when library examples don't actually work
anymore due to API changes (or typos).

There's actually a really great solution in the Rust ecosystem that I would
love to see used more widely - Skeptic [0]. It's a tool that parses markdown,
finds Rust and builds it as an auto-generated test. If the example is no
longer valid, it breaks your build.

[0] - [https://github.com/budziq/rust-skeptic](https://github.com/budziq/rust-
skeptic)

~~~
steveklabnik
So, to be clear, skeptic helps with extra markdown files you've written.
Rustdoc will already do this with every example you write in your API
documentation. It's very good though! (mdbook has a similar feature)

~~~
joshmarlow
Good point - thanks for calling it out!

------
HugoDaniel
I wish there was something similar to the Haskell Haddock
([https://www.haskell.org/haddock/](https://www.haskell.org/haddock/)) for
Rust.

Something that would automatically generate the signatures and modules entry
points/data types. These seem to be very neglected and generally hard to keep
up-to-date in the Rust ecosystem.

~~~
codetrotter
I am not familiar with Haddock, as I've barely touched Haskell, but I do write
a fair bit of Rust.

Perhaps I am reading your comment wrong, but:

\- Generated Rust crate docs include signatures for all of their public
functions, and

\- Generated Rust crate docs include public enums, public fields of public
structs, etc

------
imtringued
Does rust-doc make a distinction between a user guide and a reference? A user
guide is basically a book that goes over all the general features of the
library. A reference provides information about the API of the library.

~~~
steveklabnik
So, the terminology I've used since around 2013:

* API documentation: stuff like "type signatures"

* Reference documentation: the specification of the language

* Tutorials: long-form text that explains things

I gave a talk about the Bay Area Rust Meetup about this, but it seems like
maybe it's lost to history :(

Anyway, rustdoc makes this distinction in a sense because it only provides API
documentation, which I believe is what you're calling "reference"
documentation. mdbook provides the longer form factor.

Most libraries don't have a language spec, since they're not a language, so
they have categories one and three.

