7 ms·

How to write documentation for a Rust crate

115 points by lukastyrychtr 7y ago

jnordwick 7y ago
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/java/lang/String.html https://docs.oracle.com/en/java/javase/11/docs/api/java.base... 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.
- dijit 7y ago
  You know. I thought it was just me who was dumb. I write a fair amount of python and /sometimes/ the docs are confusing; but the rust docs to me are completely useless. I see people like Jon Gjengset navigating perfectly fine though. I tend to reach for the examples/ directory, or the tests
- vhakulinen 7y ago
  > Why does the rust documentation still suck? Thats a bit harsh. Yes, the documentation might be (is) a bit hard to read in a sense that its hard to _find_ something from it, but otherwise I've found if quite complete (when it comes to the standard library). Most (if not all) of your points are about the readability of the rendered documentation and not the documentation (content) it self.
  - jnordwick 7y ago
    Yes, almost all my complaints about rust doc is in formatting, sectioning, and grouping. The content is good. But those display issues make it unusable unless you know what you are already looking for.
- henrikeh 7y ago
  To add another, the C++ reference has an extremely useful section for exploring any piece of documentation: "See also" Look at this page for `capacity`: https://en.cppreference.com/w/cpp/string/basic_string/capacity https://en.cppreference.com/w/cpp/string/basic_string/capaci... Immediately, I see what other methods are relevant in this same context. So many languages references are simply enumerations of items in the library, but they don't provide the context needed to actually gain proficiency in the tool and learn incrementally.
- trevyn 7y ago
  To be fair, you’re comparing a 9-year-old language with 25- and 35-year-old languages. Out of curiosity, is there anything other than the docs that prevents you from working with Rust more?
- the8472 7y ago
  There's an open issue for indices. https://github.com/rust-lang/rust/issues/40273 https://github.com/rust-lang/rust/issues/40273 And various other open issues to improve styling. I wouldn't call them useless though, clicking the [-] collapses all comments and gives a somewhat useful overview of what's available. It's far from ideal, but still useful.
- jasode 7y ago
  >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. It looks like Rust docs webpages default to expanded view instead of collapsed view. You can press [-][+] in the upper right hand corner to get a more summarized view that looks more like the cppreference example. Example video : https://imgur.com/a/EqnzAD3 https://imgur.com/a/EqnzAD3 It doesn't address all your bullet points but that may help give the reader a high level overview.
  - jnordwick 7y ago
    I know, but not even close to the same thing. Those one line summaries that make scanning easy are very useful.
- izacus 7y ago
  And your post doesn't even mention that many of crates, even important ones like crypto, aren't even fully documented and it's very common to just hit the wall of missing entries and no over-arching manual on how the crate should be used.
- bpicolo 7y ago
  I'm kind of intrigued how widely opinions differ here. I consider the Rust docs here dramatically better due to their focus on soft documentation. I can't stand Java docs.
  - imtringued 7y ago
    References are not meant to provide "soft documentation". Guides are supposed to do that.
    - dfinninger 7y ago
      I personally prefer Rust's style here to Java, and a good deal over C++. I had to learn Java last year and--even as an experienced programmer--the guides we're pretty miserable. The info was there and it was terse [1], but I wound up paying for a course elsewhere because the official docs weren't working for me. Rust method here of combining the guide (Struct docs) and reference (Methods) is vastly superior, in my opinion. One niggle I always have with docs is that the two things are considered separate and I have do figure out which link is the one I'm looking for. God help me every time I need to find the String functions in the Python docs. If you don't like looking at the guide in the Rust docs, click the "[-]" in the upper right. It'll collapse everything in the page and make it look a lot more like the C++ sample. [1] https://docs.oracle.com/javase/tutorial/java/data/strings.html https://docs.oracle.com/javase/tutorial/java/data/strings.ht...
      - jnordwick 7y ago
        It is way too difficult to find a function you don't know exists, and I'm not going memorize the api. It doesn't even come remotely close to the CPU docs. It isn't sectioned just a dumb list of methods where similar methods can be pages away from each other (eg all the methods to look up or index into a data structure should be grouped). Maybe I just have a higher standard than most rust users.
    - jzoch 7y ago
      I (and i'd assume many others) am not interested in pulling up references AND guides to figure out what I want. Rust has a 1 stop shop that not only tells me WHAT I can do but HOW with examples. Javadocs is horrible in that I see a method I want to use and then have to google for an example on how it is used. Rust >>>>>>>>>>>> Java in this regard.
- marcosdumay 7y ago
  > rust also has a unique issue in how to organize traits and other rust specific constructs. A thousand times this. It doesn't matter how well written and organized that page is, because it's completely irrelevant. The relevant information is all on the traits documentation and other libraries. Rust could use something similar to hoogle.
  - rectang 7y ago
    I agree that the way traits are organized in rustdoc could be improved. It's often hard to find what the capabilities are of a given type because of what we'd call the "yo-yo problem" in OOP: you have to click through multiple levels of the hierarchy to find what you're looking for. https://en.wikipedia.org/wiki/Yo-yo_problem https://en.wikipedia.org/wiki/Yo-yo_problem
- OJFord 7y ago
  Maybe it's just what you're used to, but I massively prefer the Rust docs for `String` you linked to Java or C++'s. I think largely for one reason: the sidebar! I just scroll the sidebar for the method I know I want or a method that sounds like what I'm hoping to find, and then click it. Java & C++ both lack that, it doesn't matter so much with the latter because the page is pretty short, but Java's is huge, and to me totally unnavigable.
  - tannhaeuser 7y ago
    Old Java doc (as generated by the original javadoc tool which also inspired other languages I believe) had the kind of navigation you're looking for - it was a boxy HTML frame-based layout so it had to go, but I'm not sure why the default javadoc theme dropped in-page method navigation altogether.
- progval 7y ago
  > 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. You're linking to the reference documentation. Beginners start with the Rust Book, which covers strings: https://doc.rust-lang.org/book/ch08-02-strings.html https://doc.rust-lang.org/book/ch08-02-strings.html Besides, even the reference doc starts with five screenfuls of examples, while the Java and C++ only have two and one respectively.
- simion314 7y ago
  I think Qt documentation is very nice https://doc.qt.io/qt-5/qstring.html https://doc.qt.io/qt-5/qstring.html
- steveklabnik 7y ago
  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.
  - quietbritishjim 7y ago
    It seems like there is some low-hanging fruit that addresses one of the main complaints of the parent commenter (which I agree with). It would be nice if there was a list of all the methods with just a one line summary of each - like the sidebar but with fractionally more information. I'm thinking in terms of Doxygen's brief comments vs detailed comments here. Pages typically go (1) class brief comment, (2) list of methods with their brief comments, (3) class detailed comments (including examples), (4) method signatures and detailed comments (linked to from above). Doxygen has many serious problems but I think it gets this bit right. But a quick glance at the linked std::string::String page suggest that the first sentence of each method's docs already works as a brief summary of its function. I don't know if this is coincidence or deliberate, but if it is deliberate then the page could be reformatted just by changing the documentation system. I'm not saying that's easy, but it's less work than having to add something to every individual function.
    - steveklabnik 7y ago
      > I don't know if this is coincidence or deliberate It is conscious! This summary also shows up when you search, for example. > could be reformatted just by changing the documentation system. Yes. We've never had a bug report asking for this; I don't know how hard it would be, but it shouldn't be too tough.
- baby 7y ago
  IMO golang docs are really really good. You can just click on everything, search the std library easily, find functions you care about easily, etc.
HugoDaniel 7y ago
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 7y ago
  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
- OJFord 7y ago
  What does that do that Rust docs lack? e.g. here the signatures haven't been written manually... https://doc.rust-lang.org/std/string/struct.String.html https://doc.rust-lang.org/std/string/struct.String.html If you click 'src' at the top-right you'll see the full extent of the doc comments that generated it. (You get signatures without any comments.)
dhruvdh 7y ago
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.
- ptato 7y ago
  What do you mean you don't know? The comment explains his experience a fair bit.
- OJFord 7y ago
  > 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.
- asdkhadsj 7y ago
  I too find it quite nice. Though when I was starting out I found it exceptionally confusing. Notably the `impl` section towards the bottom. Even today, while I understand that section no problem - I don't usually find it too useful. Likely because the impls in Rust can be a bit weird. Ie Foo might impl `Responder` but only if `Foo` also implements `Serialize`, and those sort of scenarios have happened enough that I usually just ignore the bottom impl section. Not to say that the documentation is incorrect at all, I'm merely explaining how I have "adapted" to scenarios of the past - which could be confusion of my own making. But.. aside from that, I quite like Rust Docs. I also especially love how I can write tests in them, link to other types and modules like `[Foo]`. My complaint list for Rust Docs is surprisingly short honestly. Especially since they fixed the slow page loading on huge impl lists.
zelphirkalt 7y ago
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 7y ago
  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.com/blog/documentation/ https://web.archive.org/web/20200312211539/https://www.divio... [2] https://news.ycombinator.com/item?id=21289832 https://news.ycombinator.com/item?id=21289832
- imtringued 7y ago
animalnewbie 7y ago
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!
imtringued 7y ago
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 7y ago
  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.
- devit 7y ago
  The documentation for crates, modules or struct/enum often contains a "user guide" for the item in question. I think that's better than a separate book, since in most cases that separate book would never get written.
_bxg1 7y ago
+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 7y ago
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 7y ago
  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 7y ago
    Good point - thanks for calling it out!
- asdkhadsj 7y ago
  Another approach which I've liked in the past to solve this issue is to generate your README's from Rust Source. This has the same net output but the readme lives within Rustdoc. I think I prefer it living in Rustdoc because then your README is also on docs.rs and whatnot. But, I can see some downsides with that too. Not every README should be identical to the API docs. Not sure where the balance should sit.

115 points by lukastyrychtr 7y ago

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/java/lang/String.html https://docs.oracle.com/en/java/javase/11/docs/api/java.base... 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.

dijit 7y ago
You know. I thought it was just me who was dumb. I write a fair amount of python and /sometimes/ the docs are confusing; but the rust docs to me are completely useless. I see people like Jon Gjengset navigating perfectly fine though. I tend to reach for the examples/ directory, or the tests
vhakulinen 7y ago
> Why does the rust documentation still suck? Thats a bit harsh. Yes, the documentation might be (is) a bit hard to read in a sense that its hard to _find_ something from it, but otherwise I've found if quite complete (when it comes to the standard library). Most (if not all) of your points are about the readability of the rendered documentation and not the documentation (content) it self.
- jnordwick 7y ago
  Yes, almost all my complaints about rust doc is in formatting, sectioning, and grouping. The content is good. But those display issues make it unusable unless you know what you are already looking for.
henrikeh 7y ago
To add another, the C++ reference has an extremely useful section for exploring any piece of documentation: "See also" Look at this page for `capacity`: https://en.cppreference.com/w/cpp/string/basic_string/capacity https://en.cppreference.com/w/cpp/string/basic_string/capaci... Immediately, I see what other methods are relevant in this same context. So many languages references are simply enumerations of items in the library, but they don't provide the context needed to actually gain proficiency in the tool and learn incrementally.
trevyn 7y ago
To be fair, you’re comparing a 9-year-old language with 25- and 35-year-old languages. Out of curiosity, is there anything other than the docs that prevents you from working with Rust more?
the8472 7y ago
There's an open issue for indices. https://github.com/rust-lang/rust/issues/40273 https://github.com/rust-lang/rust/issues/40273 And various other open issues to improve styling. I wouldn't call them useless though, clicking the [-] collapses all comments and gives a somewhat useful overview of what's available. It's far from ideal, but still useful.
jasode 7y ago
>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. It looks like Rust docs webpages default to expanded view instead of collapsed view. You can press [-][+] in the upper right hand corner to get a more summarized view that looks more like the cppreference example. Example video : https://imgur.com/a/EqnzAD3 https://imgur.com/a/EqnzAD3 It doesn't address all your bullet points but that may help give the reader a high level overview.
- jnordwick 7y ago
  I know, but not even close to the same thing. Those one line summaries that make scanning easy are very useful.
izacus 7y ago
And your post doesn't even mention that many of crates, even important ones like crypto, aren't even fully documented and it's very common to just hit the wall of missing entries and no over-arching manual on how the crate should be used.
bpicolo 7y ago
I'm kind of intrigued how widely opinions differ here. I consider the Rust docs here dramatically better due to their focus on soft documentation. I can't stand Java docs.
- imtringued 7y ago
  References are not meant to provide "soft documentation". Guides are supposed to do that.
  - dfinninger 7y ago
    I personally prefer Rust's style here to Java, and a good deal over C++. I had to learn Java last year and--even as an experienced programmer--the guides we're pretty miserable. The info was there and it was terse [1], but I wound up paying for a course elsewhere because the official docs weren't working for me. Rust method here of combining the guide (Struct docs) and reference (Methods) is vastly superior, in my opinion. One niggle I always have with docs is that the two things are considered separate and I have do figure out which link is the one I'm looking for. God help me every time I need to find the String functions in the Python docs. If you don't like looking at the guide in the Rust docs, click the "[-]" in the upper right. It'll collapse everything in the page and make it look a lot more like the C++ sample. [1] https://docs.oracle.com/javase/tutorial/java/data/strings.html https://docs.oracle.com/javase/tutorial/java/data/strings.ht...
    - jnordwick 7y ago
      It is way too difficult to find a function you don't know exists, and I'm not going memorize the api. It doesn't even come remotely close to the CPU docs. It isn't sectioned just a dumb list of methods where similar methods can be pages away from each other (eg all the methods to look up or index into a data structure should be grouped). Maybe I just have a higher standard than most rust users.
  - jzoch 7y ago
    I (and i'd assume many others) am not interested in pulling up references AND guides to figure out what I want. Rust has a 1 stop shop that not only tells me WHAT I can do but HOW with examples. Javadocs is horrible in that I see a method I want to use and then have to google for an example on how it is used. Rust >>>>>>>>>>>> Java in this regard.
marcosdumay 7y ago
> rust also has a unique issue in how to organize traits and other rust specific constructs. A thousand times this. It doesn't matter how well written and organized that page is, because it's completely irrelevant. The relevant information is all on the traits documentation and other libraries. Rust could use something similar to hoogle.
- rectang 7y ago
  I agree that the way traits are organized in rustdoc could be improved. It's often hard to find what the capabilities are of a given type because of what we'd call the "yo-yo problem" in OOP: you have to click through multiple levels of the hierarchy to find what you're looking for. https://en.wikipedia.org/wiki/Yo-yo_problem https://en.wikipedia.org/wiki/Yo-yo_problem
OJFord 7y ago
Maybe it's just what you're used to, but I massively prefer the Rust docs for `String` you linked to Java or C++'s. I think largely for one reason: the sidebar! I just scroll the sidebar for the method I know I want or a method that sounds like what I'm hoping to find, and then click it. Java & C++ both lack that, it doesn't matter so much with the latter because the page is pretty short, but Java's is huge, and to me totally unnavigable.
- tannhaeuser 7y ago
  Old Java doc (as generated by the original javadoc tool which also inspired other languages I believe) had the kind of navigation you're looking for - it was a boxy HTML frame-based layout so it had to go, but I'm not sure why the default javadoc theme dropped in-page method navigation altogether.
progval 7y ago
> 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. You're linking to the reference documentation. Beginners start with the Rust Book, which covers strings: https://doc.rust-lang.org/book/ch08-02-strings.html https://doc.rust-lang.org/book/ch08-02-strings.html Besides, even the reference doc starts with five screenfuls of examples, while the Java and C++ only have two and one respectively.
simion314 7y ago
I think Qt documentation is very nice https://doc.qt.io/qt-5/qstring.html https://doc.qt.io/qt-5/qstring.html
steveklabnik 7y ago
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.
- quietbritishjim 7y ago
  It seems like there is some low-hanging fruit that addresses one of the main complaints of the parent commenter (which I agree with). It would be nice if there was a list of all the methods with just a one line summary of each - like the sidebar but with fractionally more information. I'm thinking in terms of Doxygen's brief comments vs detailed comments here. Pages typically go (1) class brief comment, (2) list of methods with their brief comments, (3) class detailed comments (including examples), (4) method signatures and detailed comments (linked to from above). Doxygen has many serious problems but I think it gets this bit right. But a quick glance at the linked std::string::String page suggest that the first sentence of each method's docs already works as a brief summary of its function. I don't know if this is coincidence or deliberate, but if it is deliberate then the page could be reformatted just by changing the documentation system. I'm not saying that's easy, but it's less work than having to add something to every individual function.
  - steveklabnik 7y ago
    > I don't know if this is coincidence or deliberate It is conscious! This summary also shows up when you search, for example. > could be reformatted just by changing the documentation system. Yes. We've never had a bug report asking for this; I don't know how hard it would be, but it shouldn't be too tough.
baby 7y ago
IMO golang docs are really really good. You can just click on everything, search the std library easily, find functions you care about easily, etc.

HugoDaniel 7y ago

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 7y ago
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
OJFord 7y ago
What does that do that Rust docs lack? e.g. here the signatures haven't been written manually... https://doc.rust-lang.org/std/string/struct.String.html https://doc.rust-lang.org/std/string/struct.String.html If you click 'src' at the top-right you'll see the full extent of the doc comments that generated it. (You get signatures without any comments.)

dhruvdh 7y ago

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.

ptato 7y ago
What do you mean you don't know? The comment explains his experience a fair bit.
OJFord 7y ago
> 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.
asdkhadsj 7y ago
I too find it quite nice. Though when I was starting out I found it exceptionally confusing. Notably the `impl` section towards the bottom. Even today, while I understand that section no problem - I don't usually find it too useful. Likely because the impls in Rust can be a bit weird. Ie Foo might impl `Responder` but only if `Foo` also implements `Serialize`, and those sort of scenarios have happened enough that I usually just ignore the bottom impl section. Not to say that the documentation is incorrect at all, I'm merely explaining how I have "adapted" to scenarios of the past - which could be confusion of my own making. But.. aside from that, I quite like Rust Docs. I also especially love how I can write tests in them, link to other types and modules like `[Foo]`. My complaint list for Rust Docs is surprisingly short honestly. Especially since they fixed the slow page loading on huge impl lists.

zelphirkalt 7y ago

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 7y ago
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.com/blog/documentation/ https://web.archive.org/web/20200312211539/https://www.divio... [2] https://news.ycombinator.com/item?id=21289832 https://news.ycombinator.com/item?id=21289832
imtringued 7y ago

animalnewbie 7y ago

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!

imtringued 7y ago

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 7y ago
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.
devit 7y ago
The documentation for crates, modules or struct/enum often contains a "user guide" for the item in question. I think that's better than a separate book, since in most cases that separate book would never get written.

_bxg1 7y ago

+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 7y ago

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 7y ago
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 7y ago
  Good point - thanks for calling it out!
asdkhadsj 7y ago
Another approach which I've liked in the past to solve this issue is to generate your README's from Rust Source. This has the same net output but the readme lives within Rustdoc. I think I prefer it living in Rustdoc because then your README is also on docs.rs and whatnot. But, I can see some downsides with that too. Not every README should be identical to the API docs. Not sure where the balance should sit.