Hacker News Reader

Comment by verandaguy | Hacker News Reader

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

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

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...

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.

Are there any ways the community can give back, and help work on the docs? A wiki maybe?

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!

Docs are maintained here: 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

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

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.

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.)

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/ They haven't yet been linked because of all the FIXMEs.

Thanks for the suggestions. :)

Just out of curiousity, why not use reStructuredText?

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.

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.

There's a lot of stuff we'd like to do with the site, for sure. Always so much to do...

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.

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 :)

The two maps with PartialOrd are

https://doc.rust-lang.org/collections/struct.BTreeMap.html

https://doc.rust-lang.org/collections/vec_map/struct.VecMap....

ChaChaRng is

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 :).

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, which has an explanation of what it does. Am I missing something?

ChaChaRng _does_ mention OsRng, but a code sample might help, for sure.

> I'm not sure what _specifically_ the issue is here with PartialOrd.

I know what a partial order is, I just don't know what partial order maps realize. In Python they aren't orderable.

> ChaChaRng _does_ mention OsRng

It says to use OsRng if cryptographic security is needed, not how to seed with it.

The obvious way is something like

    let osrng = OsRng::new().unwrap();
    let mut key = [0u32; 8];
    for word in key.iter_mut() {
        *word = osrng.gen();
    }
    let prng = ChaChaRng::from_seed(&key[..])

which is a pain.

Roger, I see what you're saying, on both counts.

Thank you for taking the time to spell it out to me.

Maps can be compared lexicographically. BTreeMap and VecMap have a canonical order in which they store their elements so

  iter::order::cmp(self.iter(), other.iter())

works as an ordering.

HashMap in Rust (dict in Python) doesn't have a canonical ordering of elements, so this doesn't make sense.

Reply on news.ycombinator.com