8 ms·

I've always found crate documentation to be the worse thing about Rust. Because it auto-generates some documentation, people just assume that's good enough, and

I've always found crate documentation to be the worse thing about Rust. Because it auto-generates some documentation, people just assume that's good enough, and you end up with tonnes of crates that seemingly only have a list of functions and structs and what arguments they take, but very little information about how you're supposed to plug everything together.

lights0123 6y ago
> people just assume that's good enough really? I've found that in general the same number of people bother to go deep into explaining compared to e.g. JS, and always having rustdoc for the people that don't is far better than reading the source or TypeScript definitions.
Rusky 6y ago
Both are true, in my experience. Lots of good documentation for some crates, while others (usually with fewer maintainers or less intention of reuse) just have the autogenerated index.
throwaway894345 6y ago
At least you get that. In the (untyped) Python ecosystem, you're lucky to get "this parameter is a file-like object" even though "file-like" doesn't tell you if it just supports read() and write() or also seek() or close() or truncate(). You have to dig into the source code, which likely just passes the parameter into another function which passes it into another and then across a library boundary and so on. And again, that's the best-case scenario. Just having correct type information is 80% of the battle IMHO.
skrtskrt 6y ago
Go is the same. Everyone, including the stdlib maintainers seem to think a few lines of comments per method is the same as documentation on how to use the package, best practices, pitfalls, etc.
- x87678r 6y ago
  Java is the same as well
  - masklinn 6y ago
    So tldr: people don't like writing documentation, and it's hard to make them care.
    - hinkley 6y ago
      If you can’t tell a story with text, you won’t be able to tell it with code either. The thing that makes people want better documentation is the same thing that makes it difficult to get. I remember years ago using Ant as a build tool and the only way I figured it out was to Googlestalk the author. Given enough answers to questions in enough places I finally developed a theory of the system. It was still supremely weird to convince it to do certain things but at least I was able to.
      - masklinn 6y ago
        > If you can’t tell a story with text, you won’t be able to tell it with code either. I couldn't disagree more. Telling a story with words to humans and telling a story with code to a computer are completely different things.
        hinkley 6y ago
        You’re not telling a story to a computer. You’re telling it to your coworkers. The people’s code that’s most frustrating to work with share your philosophy. They are often so convinced they’re right that they can’t even hear constructive criticism. That’s not my opinion, that’s the consensus view shared over lunches and coffees with their coworkers, across many jobs.
  - TheAsprngHacker 6y ago
    Interestingly, documentation that's only type signatures is also a frequent gripe I've heard about OCaml. So maybe this is a universal phenomenon. However, some people contrast OCaml and Rust in this regard, contradicting the views of the great grand-parent comment: https://news.ycombinator.com/item?id=25111104 https://news.ycombinator.com/item?id=25111104

lights0123 6y ago

> people just assume that's good enough really? I've found that in general the same number of people bother to go deep into explaining compared to e.g. JS, and always having rustdoc for the people that don't is far better than reading the source or TypeScript definitions.

Rusky 6y ago

Both are true, in my experience. Lots of good documentation for some crates, while others (usually with fewer maintainers or less intention of reuse) just have the autogenerated index.

throwaway894345 6y ago

At least you get that. In the (untyped) Python ecosystem, you're lucky to get "this parameter is a file-like object" even though "file-like" doesn't tell you if it just supports read() and write() or also seek() or close() or truncate(). You have to dig into the source code, which likely just passes the parameter into another function which passes it into another and then across a library boundary and so on. And again, that's the best-case scenario. Just having correct type information is 80% of the battle IMHO.

skrtskrt 6y ago

Go is the same. Everyone, including the stdlib maintainers seem to think a few lines of comments per method is the same as documentation on how to use the package, best practices, pitfalls, etc.

x87678r 6y ago
Java is the same as well
- masklinn 6y ago
  So tldr: people don't like writing documentation, and it's hard to make them care.
  - hinkley 6y ago
    If you can’t tell a story with text, you won’t be able to tell it with code either. The thing that makes people want better documentation is the same thing that makes it difficult to get. I remember years ago using Ant as a build tool and the only way I figured it out was to Googlestalk the author. Given enough answers to questions in enough places I finally developed a theory of the system. It was still supremely weird to convince it to do certain things but at least I was able to.
    - masklinn 6y ago
      > If you can’t tell a story with text, you won’t be able to tell it with code either. I couldn't disagree more. Telling a story with words to humans and telling a story with code to a computer are completely different things.
      - hinkley 6y ago
        You’re not telling a story to a computer. You’re telling it to your coworkers. The people’s code that’s most frustrating to work with share your philosophy. They are often so convinced they’re right that they can’t even hear constructive criticism. That’s not my opinion, that’s the consensus view shared over lunches and coffees with their coworkers, across many jobs.
- TheAsprngHacker 6y ago
  Interestingly, documentation that's only type signatures is also a frequent gripe I've heard about OCaml. So maybe this is a universal phenomenon. However, some people contrast OCaml and Rust in this regard, contradicting the views of the great grand-parent comment: https://news.ycombinator.com/item?id=25111104 https://news.ycombinator.com/item?id=25111104