
Rust's new documentation generator: 95% done - cmrx64
https://mail.mozilla.org/pipermail/rust-dev/2013-August/005219.html
======
kibwen
I want to point out that this entire project was conceived and implemented by
members of the Rust community. For such a young language, I'm elated at the
quality of our community contributions.

------
mscottmcbee
Rust looks very interesting to me, but seems to be in in a state of high flux.
Does anyone have experience with sustained work in the language? How often are
you hurt by the rate of change?

~~~
btipling
It's not so much the rate of change, but maybe just how much stuff is missing
that has to be supplemented by bringing in C libraries, which is totally OK.
Rust is going to take a long time to mature, much longer than Go for example,
because the project is maybe more ambitious and doesn't have a Rob Pike or a
Brad Fitzgerald supporting it and a giant Google behind it. The risk is that
it could flounder without critical support, but Mozilla seems to be committed
to it. I hope it does well.

~~~
steveklabnik
It was also announced at an earlier part of the maturation cycle than Go was,
due to Mozilla's 'everything is all open source all the time' nature.

------
pwpwp
Looks great, but it should be easier to get back to the front page
[http://seld.be/rustdoc/master/index.html](http://seld.be/rustdoc/master/index.html)

I had to look at all links (tutorial, manual, documentation, ...) and guess
which is the right one.

~~~
Seldaek
Good point. The logo should definitely be clickable, and the menu items
clarified a bit. The navigation was sort of in a tentative state until now
since it isn't even integrated in the rust-lang.org website yet.

------
pohl
Congratulations on having it be usable on an iOS machine straight out of the
gate. This is something that still eludes scaladoc, for example.

~~~
Seldaek
Thanks I guess, but I wouldn't call it "working" just yet :)

It does render, but it seems like the search engine initialization is blocking
for quite a while on iPhones, and in portrait mode it could use some more
responsiveness.

Did you try it on an iPad or what device exactly?

~~~
pohl
It was my iPhone (5) that I tried it on, but I confess that I didn't try the
search. I was just happy to be able to navigate and read. Scaladoc has much
bigger sins than blocking the event loop for a while: it shows you the top
fragment of any given page and won't let you scroll down to see the rest.

Anyway, thank you for your work here. If you ever want me to be your iOS
guinea pig (phone or tablet) let me know.

------
Mindless2112
One thing that hurts functionality discoverability a bit is that methods are
hidden within traits. If it can be done without too much cluttering, it would
be nice for the module overview to list the functions within the traits
(without any details, e.g. type).

For example, if I am looking for the `insert` method for a vector, I sort of
have to understand something about the inner workings of `std::vec` to know
that I need to look within `std​::vec::OwnedVector` rather than, say,
`std​::vec::MutableVector`.

~~~
dbaupp
This is unfortunate, but it mostly applies to built-in types (since they don't
have a declaration anywhere). Types that are defined entirely in libraries do
have their trait implementations explicitly listed, e.g.
[http://seld.be/rustdoc/master/extra/dlist/struct.DList.html#...](http://seld.be/rustdoc/master/extra/dlist/struct.DList.html#implementations)

~~~
Mindless2112
Ah. Maybe a the built-in types could have special cases built into the doc
generator?

------
fournm
That is gorgeous and a huge step up in readability over the previous docs (and
most others that I see, honestly). Amazing work, everyone involved.

------
jzelinskie
The next step is a formatter like gofmt. I really hope more languages adopt
something like gofmt over normal linters.

~~~
mhd
Wouldn't 'indent' be the closer relative, not 'lint'?

~~~
cmrx64
Besides, rustc already does an impressive amount of linting.

------
cpeterso
I would love to see the docs have a page with a consolidated list of all the
traits declared in the std and extra libraries. Library developers could more
easily discover additional traits they might be able to support on new
libraries without browsing through every section. Release notes could
highlight new traits too.

------
toqueteos
If only Rust had same implicit interfaces and visibility (first
uppercase/lowercase letter) as Go...

~~~
pcwalton
We can't have implicit interfaces because they're incompatible with adding
methods to types that you don't own (for example, adding methods to builtin
types like int). Having this functionality is very important for our generics
to work.

Using case for visibility is convenient but it can cause problems when you
change a method from public to private or vice versa; that's why it's not done
in Rust.

------
untothebreach
judging by the updates on the mailing list, @cmr has been working hard at
this. Congrats!

~~~
cmrx64
thanks, but Seldaek (Jordi) has been doing all the stuff with the frontend,
which is where most of praise deserves to go IMO

