6 ms·

Awesome! Now to get the STL docs up to speed and fix them up so that they're less ambiguous to newcomers!

by verandaguy 11y ago

steveklabnik 11y ago
The STL docs? And what specifically is ambiguous? (and thanks :) )
- verandaguy 11y ago
  Well, when I started learning (around Beta 2, I'm by no means an expert yet but eager to get there!) a lot of the docs about both I/O and type conversions/type casting could've used some work, just to name two features...
  - steveklabnik 11y ago
    Oh, the "T" was confusing me, you mean the standard library docs? And yeah, there's certainly a ton of weak points. We landed a _lot_ of Rustdoc fixes that make certain things better, but there's still a ton more to write. I've been mostly focusing on the longform docs. I just wanted to make sure that I know where people are having problems, so I can know where to focus my efforts. Thanks.
    - verandaguy 11y ago
      Are there any ways the community can give back, and help work on the docs? A wiki maybe?
      - steveklabnik 11y ago
        The docs are all in-tree. I love community contributed docs, that's how I got started :) Just like any GitHub project, just send us a pull request!
      - lambda 11y ago
        Docs are maintained here: https://github.com/rust-lang/rust/tree/master/src/doc https://github.com/rust-lang/rust/tree/master/src/doc The book is in the "trpl" directory: https://github.com/rust-lang/rust/tree/master/src/doc/trpl https://github.com/rust-lang/rust/tree/master/src/doc/trpl The standard library docs are maintained in doc comments in the appropriate places in the source: https://github.com/rust-lang/rust/tree/master/src/libstd https://github.com/rust-lang/rust/tree/master/src/libstd You can clone the repository, modify it locally, and build and test the docs (yes, the docs get tested, most of the code samples are actually executable tests), or you can just edit them online in GitHub's editor and send a pull request that way if you're just making documentation suggestions that won't need any tests.
- sho_hn 11y ago
  I think the main problem with the docs right now is that most people looking at them aren't just new to the API, but also new to the lang - it can be quite hard to navigate them if you don't know much about the type system and how APIs may be composed using Rust's various facilities. That is obvious, I guess, but it doesn't stop people from trying. Some way to conflate the two types of docs might be cool. For example, if there were high-level examples of commonly used API patterns in the std lib ("we use traits in this fashion here to achieve the following goals"), the docs could embed links to them as factoids ("this is an application of <this pattern>"). Heck, even just a ? button next to the "Traits" header linking to the book's Traits section would probably help some folks. Linking to rust-guidelines in some way to back up the design of various APIs might be cool, too. (Don't want to be the guy to crash Happy Day with more requests, so I'll just add: Many thanks for all your work, Rust has been tickling my brain in enjoyable ways like nothing else this year.)
  - steveklabnik 11y ago
    Yeah, it's very true. Markdown is really weak in this area too, requiring us to a do a LOT of manual wor to link things up. Oh, and rust-guidelines actually moved in tree: http://doc.rust-lang.org/stable/style/ http://doc.rust-lang.org/stable/style/ They haven't yet been linked because of all the FIXMEs. Thanks for the suggestions. :)
    - ngoldbaum 11y ago
      Just out of curiousity, why not use reStructuredText?
      - steveklabnik 11y ago
        We had a long, hard think about it. We had a fairly significant amount of Markdown, the tooling was already written, and on a more personal note, I like the idea of reStructuredText, but I _hate_ writing it. If we'd have overwhelming reason to switch, we still would have, but basically, that's why: not enough reason to overcome momentum. ASCIIDoc or something else might be nice too.
- worklogin 11y ago
  Steve, wouldn't it be good for the homepage of Rust to have a small news banner/sidebar, so people landing there would be presented with big news? I do like the homepage for its simplicity, but no-one would know the significance without digging into the 'community' links. If that doesn't seem like an issue, then nevermind. Just a thought. edit to explain: I'm at work and can't hop into IRC to chat about it.
  - steveklabnik 11y ago
    There's a lot of stuff we'd like to do with the site, for sure. Always so much to do...
- Veedrac 11y ago
  Do you deal with documentation on parts that have been moved out of std, too? Some of the hardest parts of the documentation is the functionality hidden behind `impl SomeTrait for SomeStruct`. Eg. `impl PartialOrd for BTreeMap`. What on earth does that do? Or the fact you're meant to make a randomly seeded `ChaChaRng` with `OsRng::new().unwrap().gen()`, which is genius but impossible to guess.
  - steveklabnik 11y ago
    In theory, yes, but I spend most of my time on what's most important, which is the stuff in-tree. I've even been neglecting Cargo, which could use a reorganizaiton at least. Those implementations should absolutely be in the generated documentation, can you maybe point me to some specific pages? Thanks :)
    - Veedrac 11y ago
      The two maps with PartialOrd are https://doc.rust-lang.org/collections/struct.BTreeMap.html https://doc.rust-lang.org/collections/struct.BTreeMap.html https://doc.rust-lang.org/collections/vec_map/struct.VecMap.html https://doc.rust-lang.org/collections/vec_map/struct.VecMap.... ChaChaRng is http://doc.rust-lang.org/rand/rand/chacha/struct.ChaChaRng.html http://doc.rust-lang.org/rand/rand/chacha/struct.ChaChaRng.h... although the other implementations also need this. The main page for rand should probably have this somewhere on it, too. Thanks for helping :).
      - steveklabnik 11y ago
        Thanks. So, I'm not sure what _specifically_ the issue is here with PartialOrd. It has 'impl<K: PartialOrd, V: PartialOrd> PartialOrd for BTreeMap<K, V>', and if you click on PartialOrd, you go to https://doc.rust-lang.org/core/cmp/trait.PartialOrd.html https://doc.rust-lang.org/core/cmp/trait.PartialOrd.html, which has an explanation of what it does. Am I missing something? ChaChaRng _does_ mention OsRng, but a code sample might help, for sure.
        11y ago

Awesome! Now to get the STL docs up to speed and fix them up so that they're less ambiguous to newcomers!

steveklabnik 11y ago

The STL docs? And what specifically is ambiguous? (and thanks :) )

verandaguy 11y ago
Well, when I started learning (around Beta 2, I'm by no means an expert yet but eager to get there!) a lot of the docs about both I/O and type conversions/type casting could've used some work, just to name two features...
- steveklabnik 11y ago
  Oh, the "T" was confusing me, you mean the standard library docs? And yeah, there's certainly a ton of weak points. We landed a _lot_ of Rustdoc fixes that make certain things better, but there's still a ton more to write. I've been mostly focusing on the longform docs. I just wanted to make sure that I know where people are having problems, so I can know where to focus my efforts. Thanks.
  - verandaguy 11y ago
    Are there any ways the community can give back, and help work on the docs? A wiki maybe?
    - steveklabnik 11y ago
      The docs are all in-tree. I love community contributed docs, that's how I got started :) Just like any GitHub project, just send us a pull request!
    - lambda 11y ago
      Docs are maintained here: https://github.com/rust-lang/rust/tree/master/src/doc https://github.com/rust-lang/rust/tree/master/src/doc The book is in the "trpl" directory: https://github.com/rust-lang/rust/tree/master/src/doc/trpl https://github.com/rust-lang/rust/tree/master/src/doc/trpl The standard library docs are maintained in doc comments in the appropriate places in the source: https://github.com/rust-lang/rust/tree/master/src/libstd https://github.com/rust-lang/rust/tree/master/src/libstd You can clone the repository, modify it locally, and build and test the docs (yes, the docs get tested, most of the code samples are actually executable tests), or you can just edit them online in GitHub's editor and send a pull request that way if you're just making documentation suggestions that won't need any tests.
sho_hn 11y ago
I think the main problem with the docs right now is that most people looking at them aren't just new to the API, but also new to the lang - it can be quite hard to navigate them if you don't know much about the type system and how APIs may be composed using Rust's various facilities. That is obvious, I guess, but it doesn't stop people from trying. Some way to conflate the two types of docs might be cool. For example, if there were high-level examples of commonly used API patterns in the std lib ("we use traits in this fashion here to achieve the following goals"), the docs could embed links to them as factoids ("this is an application of <this pattern>"). Heck, even just a ? button next to the "Traits" header linking to the book's Traits section would probably help some folks. Linking to rust-guidelines in some way to back up the design of various APIs might be cool, too. (Don't want to be the guy to crash Happy Day with more requests, so I'll just add: Many thanks for all your work, Rust has been tickling my brain in enjoyable ways like nothing else this year.)
- steveklabnik 11y ago
  Yeah, it's very true. Markdown is really weak in this area too, requiring us to a do a LOT of manual wor to link things up. Oh, and rust-guidelines actually moved in tree: http://doc.rust-lang.org/stable/style/ http://doc.rust-lang.org/stable/style/ They haven't yet been linked because of all the FIXMEs. Thanks for the suggestions. :)
  - ngoldbaum 11y ago
    Just out of curiousity, why not use reStructuredText?
    - steveklabnik 11y ago
      We had a long, hard think about it. We had a fairly significant amount of Markdown, the tooling was already written, and on a more personal note, I like the idea of reStructuredText, but I _hate_ writing it. If we'd have overwhelming reason to switch, we still would have, but basically, that's why: not enough reason to overcome momentum. ASCIIDoc or something else might be nice too.
worklogin 11y ago
Steve, wouldn't it be good for the homepage of Rust to have a small news banner/sidebar, so people landing there would be presented with big news? I do like the homepage for its simplicity, but no-one would know the significance without digging into the 'community' links. If that doesn't seem like an issue, then nevermind. Just a thought. edit to explain: I'm at work and can't hop into IRC to chat about it.
- steveklabnik 11y ago
  There's a lot of stuff we'd like to do with the site, for sure. Always so much to do...
Veedrac 11y ago
Do you deal with documentation on parts that have been moved out of std, too? Some of the hardest parts of the documentation is the functionality hidden behind `impl SomeTrait for SomeStruct`. Eg. `impl PartialOrd for BTreeMap`. What on earth does that do? Or the fact you're meant to make a randomly seeded `ChaChaRng` with `OsRng::new().unwrap().gen()`, which is genius but impossible to guess.
- steveklabnik 11y ago
  In theory, yes, but I spend most of my time on what's most important, which is the stuff in-tree. I've even been neglecting Cargo, which could use a reorganizaiton at least. Those implementations should absolutely be in the generated documentation, can you maybe point me to some specific pages? Thanks :)
  - Veedrac 11y ago
    The two maps with PartialOrd are https://doc.rust-lang.org/collections/struct.BTreeMap.html https://doc.rust-lang.org/collections/struct.BTreeMap.html https://doc.rust-lang.org/collections/vec_map/struct.VecMap.html https://doc.rust-lang.org/collections/vec_map/struct.VecMap.... ChaChaRng is http://doc.rust-lang.org/rand/rand/chacha/struct.ChaChaRng.html http://doc.rust-lang.org/rand/rand/chacha/struct.ChaChaRng.h... although the other implementations also need this. The main page for rand should probably have this somewhere on it, too. Thanks for helping :).
    - steveklabnik 11y ago
      Thanks. So, I'm not sure what _specifically_ the issue is here with PartialOrd. It has 'impl<K: PartialOrd, V: PartialOrd> PartialOrd for BTreeMap<K, V>', and if you click on PartialOrd, you go to https://doc.rust-lang.org/core/cmp/trait.PartialOrd.html https://doc.rust-lang.org/core/cmp/trait.PartialOrd.html, which has an explanation of what it does. Am I missing something? ChaChaRng _does_ mention OsRng, but a code sample might help, for sure.
      - 11y ago