Rust documentation is frustrating, I want to explain

1

My example is this

This is from: File in std::fs - Rust

#![feature(file_buffered)]
use std::fs::File;
use std::io::Write;

fn main() -> std::io::Result<()> {
    let mut f = File::create_buffered("foo.txt")?;
    assert!(f.capacity() > 0);
    for i in 0..100 {
        writeln!(&mut f, "{i}")?;
    }
    f.flush()?;
    Ok(())
}

Yes, it works it shows the process - but as a new rust person it is not enough.

For example the statement:

     let mut f = File::create_buffered("filename")?;

uses the "implied type" for the variable F.
For documentation purposes it should not, it should have the type specified.

In my case I am looking up how to open a file - yes, I know that type type of F can be determined based upon the assignment. But that's point - a new person to rust does not have that background.

I want to create a function that return what I know from C is a "FILE *" handle but I want to return the "rust equal" - I don't want to use the c_lib::FILE, which I know about because Google is not finding what I am looking for.

My statement is simply this:

In Oficial rust documentation do not be terse and barely just enough to compile and nomore. Instead it should be verbose and complete. Be overly flowery in your examples provided as documentation.

IMHO it is better to have two examples - (1) the flowery complete one and (2) the terse one with all the bells and whistles in play. Being able to compare and contrast the two implementations help others learn these tricks.

The NOOBS like me - would benefit from this far more verbose descriptions a great deal.

Most of you that I think will read and respond to this are are what I would call RUST-MUNKs (ie: Like the PERL MONKS ... know this stuff like the back of your hand so you can when you lookup and transpose something you know you can skip certain steps.

PERL did that and at times I remember trying to write the best PERL one liners... While cool they do not help people learn the langue from the the documentation - especially when all that is present in the docs are are various forms of terse one-liner type things.

I know many who had no end of problems with $_ in PERL, and you probably hate things like $_ in PERL but here you are as a group you are doing the same thing as PERL did but in the RUST way.

its a suggestion it would help if during your review process you set a standard that things are not done in cryptic shorthand but more deliberat

1 Like
2

If you look a few lines up, the docs show you exactly what type create_buffered returns (Result<BufWriter<File>>). If any of those types are unclear to you, you can click on them to be taken to their respective documentation pages.

Could you be a little more specific about what your concerns are?

4 Likes
3

Nor is it meant to be.

The examples in the documentation are not intended to stand alone, and are intended to show how the item/s being documented should be used in practice. Annotating lets with type information would be redundant with the first goal, and counterproductive to the second. However, you're absolutely correct to observe that this puts more work on the reader to build their understanding, as they must look at not only the examples, but also the documentation for various symbols used in those examples.

By the time the reader is looking at library documentation, they're expected to also have a baseline level of language knowledge, which can be built up by following the book. Reiterating those lessons in each library item would be tedious, redundant, and very hard to maintain.

To your point:

You can determine this from the example plus the rest of File's documentation. The example starts with File::create_buffered("foo.txt")?, which provides some value that can then be used for writing data. The type you need must be related to the return type of this method, which is then documented here:

pub fn create_buffered<P: AsRef<Path>>(path: P) -> Result<BufWriter<File>>

The ? operator is documented here, which is not very discoverable from within the library documentation, but the short version is that it peels the Ok type out of a Result if possible, leaving you with BufWriter<File> - which is exactly the type that you're looking for. You can then read the docs for BufWriter and for File to further understand what this type is and how to use it, and to make some decisions about how to handle your specific needs.

All of that said, suggestions and feedback are valuable. Thank you for sharing where the documentation felt inadequate or incomplete! I offer only insight into why it is the way it is and into strategies for using it, and not a rejection of your position.

8 Likes
4

Get the compiler to figure it out for you. Write the function as -> _ and the compiler error will tell you the type that your function is actually returning.

error[E0121]: the placeholder `_` is not allowed within types on item signatures for return types
 --> src/lib.rs:2:17
  |
2 | fn open_it() -> _ {
  |                 ^
  |                 |
  |                 not allowed in type signatures
  |                 help: replace with the correct return type: `Result<File, std::io::Error>`

I think it's important that the library examples are roughly representative of how people write code. In rust it's normal that you don't annotate the types of every single variable, so the library examples shouldn't do that either.

5

Documentation != Learning Tool

If you are completely new to a topic/language you should probably start with something that was curated and follows a specific flow for explanations such as a book which has been suggested previously.

The documentation on the other hand is for people like me who use Rust every day but cannot remember every library function name and just want to have a quick glance in order to get something that works. In essence the documentation is for technical people with some level of background knowledge.

To be honest, when I compare the documentation of the standard library of Rust, with standard libraries of other languages, I think that it is done very nicely. For me it find's the balance between expressiveness and conciseness.

3 Likes
6

These ideas relate to two complimentary forms of "documentation", they are discussed in great detail here: https://diataxis.fr/

To borrow their terminology: rust doc is a reference. I think it is much harder to discover other forms of documentation for all of rust, such as tutorials, how to guides and explanations. But they exist. They might be articles online, YouTube videos, the book, rust by example or rustlings. Or even questions and answers on this forum.

11 Likes
7

Ah, this is great! For several years I've been contemplating that there are different forms of documentation (though my concept is not as theoretically coherent as Diataxis). But I've taken the thought a bit further.

It seems to me that many documentation collections would be improved by (1) presenting them in a unified structure based on Diataxis or some similar principle, with (2) thorough and systematic crossreferences among the different components. And furthermore, I think it would be good to have a platform (probably web-based, but it could be a desktop app too) that facilitates navigating through the different forms of documentation.

Would it be a worthwhile project? I don't know, but I would submit that it is very common for new users of Rust (or any programming language) to follow a non-linear path through learning and applying the language. I.e. for several reasons, many people will begin to use the language for real projects before they have gained a thorough mastery of the language. So while the API docs should be minimal, it would also be a good idea if they contained links to the relevant explanatory/tutorial documentation.

IDK, maybe that would be too much work in proportion to the benefit, but there's no doubt in my mind that it would be a useful thing to do.

8

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.