[Lewisham]

I'd say rustdoc is pretty rough. It's very hard to navigate the rust stdlib vs, say, Go, and when you do find what you want, it's often specified in some very cryptic manner that seems to require a PL PhD.

It is a really big barrier to adoption because it's very hard to find out what functionality is or is not offered. Here's an example: I want to iterate over a set. Easy, right?

No.

http://static.rust-lang.org/doc/master/std/collections/hash_...

Look at the signature for Cycle. It's really hard to know what this does even though it's trivial:

fn cycle(self) -> Cycle<Self> where Self: Clone

When you click through to the real documentation, it describes a useful use case for this. But that's not how programmers think. They think "I need to do X right now so I'll find something that looks right" not "I'm going to click through the documentation... oh X looks interesting I'll remember that later". There's no way to infer what Cycle really does without having actually clicked through or used it.

[TheHydroImpulse]

I actually get the opposite feeling. Maybe that's because I'm so used to rustdoc now, but it's super easy to find everything. Go's doc tool seems like just a giant dump of API signatures.

Rustdoc isn't perfect, but it's pretty easy to find things imo.

[pcwalton]

> fn cycle(self) -> Cycle<Self> where Self: Clone

I agree that a summary would be good, but this doesn't require a PL Ph.D. It means "cycle is a method that moves its receiver and returns a Cycle object of the same type of the receiver, and only works if the receiver is cloneable". The trickiest thing here, IMHO, is move semantics, which is something fundamental to Rust in general.

[vvanders]

Yup, I've got the same feeling here.

If you've spent more than a cursory time with Rust this is pretty straightforward.

You'd represent this in Java(minus move semantics, because Java has nothing like that) via:

  class IntoIter {
    public Cycle<T extends Clone> { ... }
    ...
  }

Where Clone is just an interface that knows how to clone its value.

[Lewisham]

Fair enough; some more noodling over the signature made it a bit more obvious than it seemed banged out at the back of an OSCON presentation.

I think the point still holds. Maybe just not for that one.

[vvanders]

The thing is what you linked is the docs of an implementation not the interface.

I guess I've just had a different experience. I come from almost no PL/ML background and I've found the Iterator interface in Rust(along with Option/Result) to be some of the most impressive, clear things about the language.

[megrimlock]

Perhaps there's room for a rust equivalent of cdecl, a tool to map rust to plain English descriptions, offering a gradual onramp to the syntax.

This kind of thing seems silly to experts but could raise the rate at which folks make it through language learning funnel.

[Manishearth]

I'm surprised, I find Go's doc generator to be very rudimentary. For example, you can't find the implementations of an interface, and given that interfaces are used often I have to resort to grepping the code to see what it means.

> I want to iterate over a set. Easy, right?

yes, it is easy, `for value in &set {}`. Not sure why you went all the way down to `Cycle`

In this case I agree that perhaps rustdoc should note that a full description should be alluded to (the full description of Cycle is on the Iterator trait's docs), but it's still IMO much better than go

[steveklabnik]

If you (or anyone really) has specific thoughts here, that'd be super great. Rustdoc's output could use a lot of love, but we haven't figured out exactly what we want to do with it. And having worked with it daily for a few years now, I'm personally a bit blind to its shortcomings.

[Lewisham]

Specific thought: Trait implementation pages like http://static.rust-lang.org/doc/master/std/collections/hash_... should output the first paragraph of the documentation text. That way you can easily scan/Ctrl+F through the documentation that's right next to the struct you're interested in. Reduce the number of clicks and context switches.

It's just a pretty terrifying way to output right now.

[steveklabnik]

Ah, just saw your edit. So, to be clear about what you mean, you want the Iterator implementation to show the summary line on this page? Seems reasonable to me! I filed a bug: https://github.com/rust-lang/rust/issues/33672

(Also, that page is a bit sparse because I haven't gotten around to writing any docs for it yet, so it's just the autogenerated stuff.)

[Lewisham]

Yeah, once you actually get to the text, it's really good and clearly improved from 12 months ago when I last got the free time to play around significantly.

Thanks for the bug ticket :)

[Manishearth]

Made a PR: https://github.com/rust-lang/rust/pull/33679

[blaisio]

I agree that the rust docs need work, but I disagree with your example. cycle is just a method defined as part of the Iterator implementation - it's just like a method you might define to implement an interface in Java. JavaDocs actually have the same layout as the Rust documentation in this case: you have to actually click on the method to find out how it works. This is also how docs for other languages are often laid out as well.