3 ms·

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

by 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.

3 ms·

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

by rspeer 10y ago

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.