Rust's new documentation generator: 95% done | Hacker News Reader

Rust's new documentation generator: 95% done

mail.mozilla.org

80 pointscmrx6428 comments

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.

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?

It's still pre-alpha, don't use it if you don't want to be dealing with daily backwards-incompatible changes (mostly in the libraries), occasional language features being modified or removed, etc.

I think by 0.8 or 0.9 the language itself will be able to be unofficially backwards-compatible, but we'll see.

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.

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.

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

Plus, unlike Go, they go for an iterative refinement and design, and don't settle for the first BS implementation that comes to their mind.

Recently I tried to build a rust project (just to play a bit around with the language and the tool). The code was too new to build with the latest stable (0.7) but too old to build with the latest nightly. Servo (web rendering engine) even says which git version of rust to checkout to be able to build it.

Rust is at the moment not usable for productive code. They are still experimenting and changing things quite drastically. But I think that's a good thing. I'd rather wait another year for Rust and have a mature well-thought-out language. I've waited long enough for something like Rust I can wait a little longer.

It's probably going to be more than a year before Rust is ready for productive software at the current rate and given the breadth of what's missing. There is a lot of passionate activity so it will probably make it, hopefully maybe more in 3-5 years time.

I have been fooling with it for a while, and yes, the rate of change is pretty painful. For example, there have been two significant changes to iterators recently: first the relatively minor change to (internal) iterator functions to return bool, allowing them to be nested, and then the complete revision to external iterators.

The libraries are also in a high state of flux, with stand-alone functions being replaced by trait methods and some functionality disappearing or being replaced.

http://maniagnosis.crsr.net/2013/07/letterpress-cheating-in-...

Looks great, but it should be easier to get back to the front page http://seld.be/rustdoc/master/index.html

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

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.

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

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?

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.

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

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

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

This threw me off as well.

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.

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

`rustc` already has a `--pretty` flag, though it's not great, and has bit-rotted a bit.

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

Besides, rustc already does an impressive amount of linting.

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.

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

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.

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

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

Reply on news.ycombinator.com