3 ms·

The "traits" feature of Rust's type system provides a lot of nice polymorphism and general ergonomics, but one consequence of its existence is that you see a lo

The "traits" feature of Rust's type system provides a lot of nice polymorphism and general ergonomics, but one consequence of its existence is that you see a lot of trait-related noise in the docs and it's maybe emphasized more than it should be by the styling. If you know Rust, it's pretty easy to cut through it if you know what you're looking for, and sometimes it's actually useful.

moosingin3space 10y ago
I wonder if it would be useful if the docs offered a "what functions should my type have" hint for trait-heavy functions. That way all the required functions are in the same place. Paging steveklabnik, what do you think?
- caconym_ 10y ago
  What exactly do you mean by this? Could you provide an example? Personally I think some big gains in documentation clarity could be made by sorting the methods differently, possibly more compactly; I remember when I was first starting with Rust it was easy to overlook trait impls, e.g. a useful `Deref<[T]>` implementation because they tend to show up further down in the docs. I might also have benefited from a clearer overview of all the core traits in one place, especially the ones having to do with taking references. IIRC `Deref`, `Borrow`, and `AsRef` are all different traits and the differences between them (and how to idiomatically use them in common patterns) are not totally clear. But maybe I just skipped a chapter of "the book" or something.
rspeer 10y ago
One thing I've noticed is that the answer to "how do I use this library?" is often hidden away in a sub-page about one of the traits it defines. Many libraries are made of boring top-level code and then interesting trait implementations. Structuring the documentation like the code doesn't work out very well in that case.
- caconym_ 10y ago
  I think that out of all the bad things about Haskell that may or may not be reflected in Rust, this is one that annoys me the most: a lot of libraries have very strange interfaces that they do a poor job of explaining, often seemingly enabled by fancy uses of the type system. A recent example I ran into is formatted reading/writing of date/time objects in the `chrono` crate, which seems to be the blessed option for all I can find on Google. Anyway, just getting the bare minimum functionality that I could use in other languages by calling e.g. `strftime("%Y-%m-%d")` required researching a bunch of interlocking types and traits scattered across the crate, documentation nearly or entirely absent, and resulted in some pretty ugly code to boot. I expect that the interface works this way in an attempt to avoid parsing format strings at run time ("zero cost abstractions" and all that), and that's great, but the lack of documentation made it pretty miserable to use, and I would classify my Rust skills as "intermediate". I expect a beginner would have just given up (and taken to HN to complain about the learning curve).
  - rspeer 10y ago
    This is something I've seen, but does it apply to chrono? I'm looking at its README on GitHub (https://github.com/chronotope/chrono https://github.com/chronotope/chrono), and useful examples are right there up front. DateTime::format seems to do the same thing as strftime, with a format string parsed at run-time.

moosingin3space 10y ago

I wonder if it would be useful if the docs offered a "what functions should my type have" hint for trait-heavy functions. That way all the required functions are in the same place. Paging steveklabnik, what do you think?

caconym_ 10y ago
What exactly do you mean by this? Could you provide an example? Personally I think some big gains in documentation clarity could be made by sorting the methods differently, possibly more compactly; I remember when I was first starting with Rust it was easy to overlook trait impls, e.g. a useful `Deref<[T]>` implementation because they tend to show up further down in the docs. I might also have benefited from a clearer overview of all the core traits in one place, especially the ones having to do with taking references. IIRC `Deref`, `Borrow`, and `AsRef` are all different traits and the differences between them (and how to idiomatically use them in common patterns) are not totally clear. But maybe I just skipped a chapter of "the book" or something.

rspeer 10y ago

One thing I've noticed is that the answer to "how do I use this library?" is often hidden away in a sub-page about one of the traits it defines. Many libraries are made of boring top-level code and then interesting trait implementations. Structuring the documentation like the code doesn't work out very well in that case.

caconym_ 10y ago
I think that out of all the bad things about Haskell that may or may not be reflected in Rust, this is one that annoys me the most: a lot of libraries have very strange interfaces that they do a poor job of explaining, often seemingly enabled by fancy uses of the type system. A recent example I ran into is formatted reading/writing of date/time objects in the `chrono` crate, which seems to be the blessed option for all I can find on Google. Anyway, just getting the bare minimum functionality that I could use in other languages by calling e.g. `strftime("%Y-%m-%d")` required researching a bunch of interlocking types and traits scattered across the crate, documentation nearly or entirely absent, and resulted in some pretty ugly code to boot. I expect that the interface works this way in an attempt to avoid parsing format strings at run time ("zero cost abstractions" and all that), and that's great, but the lack of documentation made it pretty miserable to use, and I would classify my Rust skills as "intermediate". I expect a beginner would have just given up (and taken to HN to complain about the learning curve).
- rspeer 10y ago
  This is something I've seen, but does it apply to chrono? I'm looking at its README on GitHub (https://github.com/chronotope/chrono https://github.com/chronotope/chrono), and useful examples are right there up front. DateTime::format seems to do the same thing as strftime, with a format string parsed at run-time.