5 ms·

I was following along until this: > universally terrible documentation and lacking examples, unstable APIs, type annotation hell, and so much more. The docs i

I was following along until this: > universally terrible documentation and lacking examples, unstable APIs, type annotation hell, and so much more. The docs in Rust are by far some of the best I've seen, without specifics it's really hard to understand what issues he hit.

b0rsuk 9y ago
They're completely different kind of docs that Python's. Python's are written by hand, with many examples and tips how to use the various tools. Rust's documentation very much feels generated, and the last time I checked methods were not grouped. So vast portions of a page are consumed by variants of methods (overloaded methods?) which work exactly the same except they take different argument type. Python documentation is text with methods and code samples inbetween. Rust's documentation is like someone iterated over functions and types and printed a message for each. There's A LOT of redundancy.
- Yoric 9y ago
 Side-note: I personally vastly prefer Rust's documentation to Python's, but I imagine it's a matter of taste. So you'd suggest adding a manner of grouping methods in rustdoc?
 - k__ 9y ago
 Also, common use-cases. Collections, strings, dates, asynchonous operations.
- vvanders 9y ago
 You mean like how Vec has a ton of examples? https://doc.rust-lang.org/std/vec/struct.Vec.html https://doc.rust-lang.org/std/vec/struct.Vec.html FWIW I'm not a huge fan of Python's docs because I can't quickly scan them to track down that one detail about a function I was using. Rust's docs also let you collapse everything which makes browsing them much faster.
 - andromeduck 9y ago
 The traits implementation section is god awful and in an utterly unusable order because the ordering makes no sense. I find myself always just looking at the source to make sense of things rather than the docs which kind of defeats the point.
 - vvanders 9y ago
 That's because the trait section only shows what traits a type implements. If you want to see how to use a trait just click that trait's name for the trait specific documentation.
 - Paul-ish 9y ago
 Sometime I don't know what trait I need, but I do know what kind of operation I want. In documentation such as Python's, I can "ctrl + F" for word similar to what I want to do and I usually find what I need. In rust, that textual description is usually hidden on the trait's page. This is probably more frustrating to beginners who don't know what most of the basic traits are. In general though, the standard library is better about this than other libraries.
 steveklabnik 9y ago
 The built-in Rustdoc search isn't perfect, but it should search the textual description for you. It might only search the first line? I should dig into that code again...
 - b0rsuk 9y ago
 Except that for some types traits form the bulk of functionality. Sorry I can't remember off top of my head, I'm a Rust novice.
 - b0rsuk 9y ago
 Vec may have examples, but lots and lots of other pages don't, and people learn by example. Python library writers add documentation similar to what they're familiar with. Rust library writers are going to document in a way that resembles typical Rust documentation. That's why I was careful to call it different, not bad. Coming from Python it's a culture shock. They are very different ways of handling documentation, and I take into account the docs are under construction. I'll try to get more used to it, see how it develops, and then form an opinion. So far Rust docs are awkward to use for me.
- whyever 9y ago
 I'm curious which docs you are talking about. The Python standard library has much less examples than Rust's in my experience. numpy has excellent documentation, but that's some library. Also, I don't see the redundancy you are talking about. There is no overloading, except for traits, and for those the documentation is in one place and all the implementations are just listed, which seems pretty minimal to me.
- wmonk 9y ago
 Coming from well established js libs to python I have found the documentation really hard to deal with. I'm not entirely sure why that is. I really like getting to a repo on github and having the docs in the readme. Both python and rust have their own language specific doc implementations ReadTheDocs and docs.rs (I think). And you usually have to go to a separate site to view them which is fine, but I really dislike ReadTheDocs. It anyways seems really hard to find what I actually want. Take flask and alembic
 - uvtc 9y ago
 I think the problem is that the Python docs often put the examples at the end, when they should be right at the top.
 - heavenlyblue 9y ago
 That's absolutely true. Python documentation severely lacks the necessary detail. Especially the newer doc format on that lighter background.
 - b0rsuk 9y ago
 The Python criticism I heard is that it makes it harder for library writers because they have to dive into source code. But here's the thing, when using a dynamic language with duck typing you don't really care what type specifically something is, only that you can iterate over it. I experienced the difference when porting someone's Python application to Rust. In Python, I didn't care what type the argument is, only what operations are performed. When writing the Rust equivalent, the Rust compiler was quick to complain it wanted to know the exact type. So I think Python docs are good for dynamic languages, while Rust documentation pleases people used to static languages.
- weberc2 9y ago
 They problem isn't that they're auto-generated, but that they're poorly organized or displayed (not sure exactly; hard to put my finger on). Everything on godoc.org (e.g., https://godoc.org/github.com/weberc2/httpeasy https://godoc.org/github.com/weberc2/httpeasy) is autogenerated and the readability is top notch. By contrast, Python (which is my day-job language) is a hot mess. Usually everything is on one page, and it's often unclear which class's `__str__` method documentation you're looking at. SQLAlchemy's docs are absolutely awful in this regard. Further, links between things are poor and inconsistent (precisely because they're not autogenerated), and the dynamic nature of the language means its up to the documentation author to be explicit about the expectations (this is less a problem for well-formed functions, but for things like Pandas where every function takes a dozen combinations of arguments, it's a nightmare).
 - b0rsuk 9y ago
 Another thing: lists of function signatures are cumbersome to read. For example: pub fn last_mut(&mut self) -> Option<&mut T> pub fn get(&self, index: I) -> Option<&>::Output> pub fn get_mut( &mut self, index: I ) -> Option<&mut >::Output> Quite often when I program I try to read the list of operations a type implements and find one that does what I need. The list above is 3 consecutive methods from Vec documentation, and it's actually from collapsed (i.e. abridged) list. I actually cut some of that collapsed info out ("where" sections) because it's not relevant at the moment. What I'm looking for at first is "last_mut", "get", "get_mut". Now the syntax is highlighted so function names are brown, but I still have to fish out function names from that soup. The "collapse" button actually hides text description, not type information. I find looking at the left side (table of contents) much more effective. But I never felt it was necessary when reading Python documentation. I don't know, maybe I'm just not used to static languages. https://doc.rust-lang.org/std/vec/struct.Vec.html https://doc.rust-lang.org/std/vec/struct.Vec.html
weavie 9y ago
I did find the documentation for promises and tokio to be pretty confusing. But I had only been learning Rust for a few days at that point, so I think I was probably just not ready for it. I went on to just use the basic sockets instead and that was pretty easy.
- littlestymaar 9y ago
  Tokio and futures are still in their infancy. We'll get there at some point hopefully
  - weavie 9y ago
    I liked the concept and will return to it when I'm a little bit more adept.
- majewsky 9y ago
  > I did find the documentation for promises and tokio to be pretty confusing. I've been learning Tokio just this week, and I think this has to do with their ongoing refactoring away from the tokio-core crate to the tokio crate.

b0rsuk 9y ago

They're completely different kind of docs that Python's. Python's are written by hand, with many examples and tips how to use the various tools. Rust's documentation very much feels generated, and the last time I checked methods were not grouped. So vast portions of a page are consumed by variants of methods (overloaded methods?) which work exactly the same except they take different argument type. Python documentation is text with methods and code samples inbetween. Rust's documentation is like someone iterated over functions and types and printed a message for each. There's A LOT of redundancy.

Yoric 9y ago
Side-note: I personally vastly prefer Rust's documentation to Python's, but I imagine it's a matter of taste. So you'd suggest adding a manner of grouping methods in rustdoc?
- k__ 9y ago
  Also, common use-cases. Collections, strings, dates, asynchonous operations.
vvanders 9y ago
You mean like how Vec has a ton of examples? https://doc.rust-lang.org/std/vec/struct.Vec.html https://doc.rust-lang.org/std/vec/struct.Vec.html FWIW I'm not a huge fan of Python's docs because I can't quickly scan them to track down that one detail about a function I was using. Rust's docs also let you collapse everything which makes browsing them much faster.
- andromeduck 9y ago
  The traits implementation section is god awful and in an utterly unusable order because the ordering makes no sense. I find myself always just looking at the source to make sense of things rather than the docs which kind of defeats the point.
  - vvanders 9y ago
    That's because the trait section only shows what traits a type implements. If you want to see how to use a trait just click that trait's name for the trait specific documentation.
    - Paul-ish 9y ago
      Sometime I don't know what trait I need, but I do know what kind of operation I want. In documentation such as Python's, I can "ctrl + F" for word similar to what I want to do and I usually find what I need. In rust, that textual description is usually hidden on the trait's page. This is probably more frustrating to beginners who don't know what most of the basic traits are. In general though, the standard library is better about this than other libraries.
      - steveklabnik 9y ago
        The built-in Rustdoc search isn't perfect, but it should search the textual description for you. It might only search the first line? I should dig into that code again...
    - b0rsuk 9y ago
      Except that for some types traits form the bulk of functionality. Sorry I can't remember off top of my head, I'm a Rust novice.
- b0rsuk 9y ago
  Vec may have examples, but lots and lots of other pages don't, and people learn by example. Python library writers add documentation similar to what they're familiar with. Rust library writers are going to document in a way that resembles typical Rust documentation. That's why I was careful to call it different, not bad. Coming from Python it's a culture shock. They are very different ways of handling documentation, and I take into account the docs are under construction. I'll try to get more used to it, see how it develops, and then form an opinion. So far Rust docs are awkward to use for me.
whyever 9y ago
I'm curious which docs you are talking about. The Python standard library has much less examples than Rust's in my experience. numpy has excellent documentation, but that's some library. Also, I don't see the redundancy you are talking about. There is no overloading, except for traits, and for those the documentation is in one place and all the implementations are just listed, which seems pretty minimal to me.
wmonk 9y ago
Coming from well established js libs to python I have found the documentation really hard to deal with. I'm not entirely sure why that is. I really like getting to a repo on github and having the docs in the readme. Both python and rust have their own language specific doc implementations ReadTheDocs and docs.rs (I think). And you usually have to go to a separate site to view them which is fine, but I really dislike ReadTheDocs. It anyways seems really hard to find what I actually want. Take flask and alembic
- uvtc 9y ago
  I think the problem is that the Python docs often put the examples at the end, when they should be right at the top.
- heavenlyblue 9y ago
  That's absolutely true. Python documentation severely lacks the necessary detail. Especially the newer doc format on that lighter background.
  - b0rsuk 9y ago
    The Python criticism I heard is that it makes it harder for library writers because they have to dive into source code. But here's the thing, when using a dynamic language with duck typing you don't really care what type specifically something is, only that you can iterate over it. I experienced the difference when porting someone's Python application to Rust. In Python, I didn't care what type the argument is, only what operations are performed. When writing the Rust equivalent, the Rust compiler was quick to complain it wanted to know the exact type. So I think Python docs are good for dynamic languages, while Rust documentation pleases people used to static languages.
weberc2 9y ago
They problem isn't that they're auto-generated, but that they're poorly organized or displayed (not sure exactly; hard to put my finger on). Everything on godoc.org (e.g., https://godoc.org/github.com/weberc2/httpeasy https://godoc.org/github.com/weberc2/httpeasy) is autogenerated and the readability is top notch. By contrast, Python (which is my day-job language) is a hot mess. Usually everything is on one page, and it's often unclear which class's `__str__` method documentation you're looking at. SQLAlchemy's docs are absolutely awful in this regard. Further, links between things are poor and inconsistent (precisely because they're not autogenerated), and the dynamic nature of the language means its up to the documentation author to be explicit about the expectations (this is less a problem for well-formed functions, but for things like Pandas where every function takes a dozen combinations of arguments, it's a nightmare).
- b0rsuk 9y ago
 Another thing: lists of function signatures are cumbersome to read. For example: pub fn last_mut(&mut self) -> Option<&mut T> pub fn get(&self, index: I) -> Option<&>::Output> pub fn get_mut( &mut self, index: I ) -> Option<&mut >::Output> Quite often when I program I try to read the list of operations a type implements and find one that does what I need. The list above is 3 consecutive methods from Vec documentation, and it's actually from collapsed (i.e. abridged) list. I actually cut some of that collapsed info out ("where" sections) because it's not relevant at the moment. What I'm looking for at first is "last_mut", "get", "get_mut". Now the syntax is highlighted so function names are brown, but I still have to fish out function names from that soup. The "collapse" button actually hides text description, not type information. I find looking at the left side (table of contents) much more effective. But I never felt it was necessary when reading Python documentation. I don't know, maybe I'm just not used to static languages. https://doc.rust-lang.org/std/vec/struct.Vec.html https://doc.rust-lang.org/std/vec/struct.Vec.html

weavie 9y ago

I did find the documentation for promises and tokio to be pretty confusing. But I had only been learning Rust for a few days at that point, so I think I was probably just not ready for it. I went on to just use the basic sockets instead and that was pretty easy.

littlestymaar 9y ago
Tokio and futures are still in their infancy. We'll get there at some point hopefully
- weavie 9y ago
  I liked the concept and will return to it when I'm a little bit more adept.
majewsky 9y ago
> I did find the documentation for promises and tokio to be pretty confusing. I've been learning Tokio just this week, and I think this has to do with their ongoing refactoring away from the tokio-core crate to the tokio crate.