dawn wind
For some reason, I find it very hard to read Rust documentation. Many people say that Rust documentation is really solid and I 100% believe that.
I primarily come from Python and I'm very used to reading docs and seeing a bunch of classes and their associated methods. Rust docs just tends to intimidate me and I end up being very confused.
If anyone could help break it down for me, that would be much appreciated.
blissful topaz
Well, first you have to understand all the item types in Rust
There are no classes like in Python
Instead, there are types that can have impls
And also there are modules, functions, etc
cold finch
Is there anything in particular that you tried to look for but had trouble finding?
dawn wind
( i do understand the basics of Rust like Traits and Structs )
at least I think I do
It's more about understanding what the docs are trying to tell me
blissful topaz
Well, they list all the public items in a crate, along with the descriptions written by the crate author
If you don't know how to get started with a crate, it's likely the failing of the crate author to make a nice getting started guide
Try looking for examples in the examples folder
dawn wind
There are a few things that confuse me.
Iterator and IntoIterator and their respective implementations.std::include_bytes. It returns &'static [u8; N] and somehow implements the Read trait. But where would I even find this in documentation?I guess those are some of the ways in which the docs really confuse me.
I end up resorting to rust-by-example since I have so much trouble reading these docs
cold finch
Auto traits are traits that rust intrinsically implements unless you use impl !Trait. Like Sync and Send. Blanket impls are traits that have a generic implementation that includes the type, like impl From<T> for T (converting from a type to itself).
Iterator means it's an actual iterator and has the next method. IntoIterator means you can convert it into an iterator with into_iter, and also that you can pass it to for loops. All Iterator automatically implement IntoIterator (this should be in the blanket implementations) and just returns itself. Often if there's similar methods, one will call the other, in which case you know it's the same. This is true for str::to_string and str::to_owned. It's a matter of style most of the time which one to pick.
blissful topaz
Rustdoc likes embedding all methods from trait impls onto the page of a type
that doesn't mean that type provides duplicate functionality
it just implements a trait
You can click the little [-] button at the top to collapse everything
That gives a nice overview without having to scroll through pages of trait impls
cold finch
For macros like include_bytes, you're relying on the author to tell you what it does. In this case, you need to know that [u8; N] is an array. This is rust knowledge and not really a documentation thing. Array references are also slices. array and slice are primitives in the standard library documentation, and you can find Read on those pages.
vital linden
Python doc is really good, and I'd argue can be more approachable than Rust, as Rust doc can be more technical reference than user guide sometimes.
Usually module level doc offers a better overview than struct. If you find yourself confused in a struct, i recommend click back to the module and see what the whole thing does, and what the struct is for, and its relationship to functions, macros, etc, as those can be at module level or in traits.
worldly sky
For example, I asked for help about std::include_bytes. It returns &'static [u8; N] and somehow implements the Read trait. But where would I even find this in documentation?
All std macros can be found at the top level page
https://doc.rust-lang.org/std/index.html#macros
or searching the web for "rust include_bytes" will also find you
https://doc.rust-lang.org/std/macro.include_bytes.html
Now, macros are slightly less automatically documented since the doc-generator can't just figure out the return type, but the prose does tell you the type.
Then to find out info about the type, a useful thing to know is that the documentation for any type whose name is punctuation can be found from the “Primitives” section https://doc.rust-lang.org/std/index.html#primitives
unfortunately it doesn't consistently list the punctuation in the summaries, but at least it's a short list.
Unfortunately the Read part isn't readily findable from this end, only from the https://doc.rust-lang.org/std/io/trait.Read.html end. But, the list of implementors of Read is a useful thing to skim to know what kinds of things you can read bytes from.