3 ms·
FWIW I find the book very easy to follow and understand, but the auto-generated docs to be kind of confusing. I think because: a) the general layout feels a b
by SCdF 9y ago
FWIW I find the book very easy to follow and understand, but the auto-generated docs to be kind of confusing.
I think because:
a) the general layout feels a bit weird to me. I can't work out which bits are important and which bits aren't. There is no table of contents or similar structure
b) as I'm still learning Rust the function signatures are often black magic to me, which adds to the confusion
https://doc.rust-lang.org/std/boxed/struct.Box.html https://doc.rust-lang.org/std/boxed/struct.Box.html is a good example.
This is a huge page, and it's overwhelming with no table of contents, or without things I probably don't care about collapsed. It is not clear to me how to use Box from this page.
Specifically for Box there is a code example on how to create a Box (great) but no indication of how to use one. Turns out you just use it and it works transparently like T would. Unlike a monad like Option or whatever. I don't know if this is obvious is you're an expert looking at the Struct signature at the top, but it's not obvious to me. It's also not obvious from the module documentation: https://doc.rust-lang.org/std/boxed/ https://doc.rust-lang.org/std/boxed/.
Then sections are broken down into different implementations against Box. Is that helpful? As a noob I don't know why that matters, I primary want a list of functions that I can interact with.
I see a lot of the function signature contains links, specifically to any other struct / trait / whatever. This is really helpful. It would also be great if there was some way of getting up to speed with parts of the structure I don't understand as well, as Rust has that Scala / Haskell trait of crazy complicated function signatures. I realise putting links on all bits is infeasible, so perhaps that is a documentation page itself, similar to how SQL structures are documented: https://www.sqlite.org/lang_select.html https://www.sqlite.org/lang_select.html
- steveklabnik 9y agoThanks! This is helpful. It’s true that the API docs are mostly written from an “I know Rust” perspective; but some of these kinds of things wouldn’t harm that. > Is that helpful? As a noob I don't know why that matters, I primary want a list of functions Yes, as it lays out the requirements for each one. Not every method is always available; it depends on what’s in the box!