On Mon, May 20, 2013 at 2:51 AM, Masklinn <[email protected]> wrote: > Yesterday as I was trying to provide more info/background for an > answer to the list, I encountered an issue which I think is going > to hinder lots of people trying out rust: using the documentation > is an exercise in frustration.
Yes, I think most people on this list will agree with you that the docs need a lot of work. I filed issues (linked below) for some of the specific problems you described. > 1. I wanted to see all the built-in ways to use Option<T> (aside > from simply pattern-matching on None and Some), for this I > went to the corresponding doc page > http://static.rust-lang.org/doc/0.6/core/option.html. Although > probably not the worst by a long shot, this page still > demonstrates a number of issues: > > - None of the methods provides examples showing off their > purpose and how they can improve code. [...] I didn't file an issue for this because it isn't something that I expect will ever be "done". It is, however, something people can start to fix right away. Adding more examples to the docs is also a low-barrier-to-entry way for someone new to start contributing to Rust. > - The only examples could actually be simpler if replaced by > using one of Option's methods, e.g. I believe the second > example > > let unwrapped_msg = match msg { > Some(m) => m, > None => ~"default message" > }; > > could have been written: > > let unwrapped_msg = msg.get_or_default(~"default message"); This, among other things, can go into a patch I'm working on to update and expand the option.rs docs. Thanks. > (and the example is incorrect in the first place, the > compiler rejects `Some(ref m) => io::println(m)`, this > should be `Some(ref m) => io::println(*m)`) It seems like the thing to do here is to extract and run code examples in the library docs, as we do already for the tutorial and manual. There's an open bug for this: https://github.com/mozilla/rust/issues/2925 This would at least make sure that the code examples compile and run without error. (Checking that the running code has the behavior we expect it to is another question, but we don't even do that now for the rest of the test suite.) > - The uniform color scheme, font and indentation make it hard > to notice e.g. admonitions (several methods will fail on a > None, have a note indicating it, but the node melds into the > rest of the document) Issue filed: https://github.com/mozilla/rust/issues/6759 > - None of the method is hyperlinked from the module's top (or > some sort of sidebar) and it's impossible to get a link to > them short of inspecting the page's HTML source Issue filed: https://github.com/mozilla/rust/issues/6760 > 2. Missing cross-section hyperlinks and references. There I was > looking for the various formats available in fmt!. fmt! is > mentioned and used extensively in the Rust tutorial[0] and is > also listed as an example macro in the reference manual[1]. > > Yet *not one* of the mentions is hyperlinked to any > specification or documentation for it. > > [...] > > Having "short syntaxes" for object-aware hyperlinks (e.g. being > able to easily link to the definition/documentation of a macro, > module, function, type or method) Issue filed: https://github.com/mozilla/rust/issues/6758 Lindsey _______________________________________________ Rust-dev mailing list [email protected] https://mail.mozilla.org/listinfo/rust-dev
