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 post - 1 participant

Read full topic