3 ms·

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

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

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