3 ms·

Does anyone else think generics detract from the usefulness of Rust docs? I often hit walls on learning libs when trying to figure out what type to use when the

Does anyone else think generics detract from the usefulness of Rust docs? I often hit walls on learning libs when trying to figure out what type to use when the API uses a generic. A non-generic flow might be like this: fn accepts param y. Param y is of type z. Docs for z shows it constructed with z::new(), or z { (fields }. When it's a generic instead, there's no link to click, and you're on your own to figure it out, possibly by browsing source code. This is exacerbated by the same libs using minimal examples that don't show the code used in a function, struct etc where explicit types are required.

Waterluvian 4y ago
I find that rust docs are entirely unhelpful for learning a library if they don’t come with plenty of realistic examples. I find the docs are just good for reference while you already generally know what you’re doing. Perhaps this is universally true of any language.
- jamesfinlayson 4y ago
  I started a Rust project last year and found the documentation pretty unhelpful for a beginner. I think Java is one that (depending on the part of the standard library) can lack any decent examples. Python and PHP's documentation generally seem to have good examples though (at least in my experience).
- rendaw 4y ago
  Yeah, I feel like learning the conventions is 90% of the battle especially with Rust. Otherwise you're playing a puzzle trying to figure out which combination of traits and objects will solve all the constraints.
- bryanlarsen 4y ago
  Poem has a ton of excellent examples.
  - the__alchemist 4y ago
    They look too simple to be useful for learning the basics. This is common with rust libs. An example of a simple, practical project demonstrating structure would be more valuable than all of them.
- lynndotpy 4y ago
  Python docs have a 'howto' that I find useful. For example, this is the Python 3 library documentation for `sockets`: https://docs.python.org/3/library/socket.html https://docs.python.org/3/library/socket.html And here is a much better introduction, the Python 3 'howto documentation' FOR `sockets`: https://docs.python.org/3/howto/sockets.html https://docs.python.org/3/howto/sockets.html It makes the Python docs a good first-stop for learning how to do things. I find the "Python ecosystem" does a good job of this. For example, I have no idea what a Cholesky decomposition is, but the Numpy docs have useful examples in their docs: https://numpy.org/doc/stable/reference/generated/numpy.linalg.cholesky.html#numpy.linalg.cholesky https://numpy.org/doc/stable/reference/generated/numpy.linal...

Waterluvian 4y ago

I find that rust docs are entirely unhelpful for learning a library if they don’t come with plenty of realistic examples. I find the docs are just good for reference while you already generally know what you’re doing. Perhaps this is universally true of any language.

jamesfinlayson 4y ago
I started a Rust project last year and found the documentation pretty unhelpful for a beginner. I think Java is one that (depending on the part of the standard library) can lack any decent examples. Python and PHP's documentation generally seem to have good examples though (at least in my experience).
rendaw 4y ago
Yeah, I feel like learning the conventions is 90% of the battle especially with Rust. Otherwise you're playing a puzzle trying to figure out which combination of traits and objects will solve all the constraints.
bryanlarsen 4y ago
Poem has a ton of excellent examples.
- the__alchemist 4y ago
  They look too simple to be useful for learning the basics. This is common with rust libs. An example of a simple, practical project demonstrating structure would be more valuable than all of them.
lynndotpy 4y ago
Python docs have a 'howto' that I find useful. For example, this is the Python 3 library documentation for `sockets`: https://docs.python.org/3/library/socket.html https://docs.python.org/3/library/socket.html And here is a much better introduction, the Python 3 'howto documentation' FOR `sockets`: https://docs.python.org/3/howto/sockets.html https://docs.python.org/3/howto/sockets.html It makes the Python docs a good first-stop for learning how to do things. I find the "Python ecosystem" does a good job of this. For example, I have no idea what a Cholesky decomposition is, but the Numpy docs have useful examples in their docs: https://numpy.org/doc/stable/reference/generated/numpy.linalg.cholesky.html#numpy.linalg.cholesky https://numpy.org/doc/stable/reference/generated/numpy.linal...