std docs: methods are really difficult to discover

[mdinger]

From reddit, rev() can be called on a CharSplits but there is no easy way to discover this without being told.

for word in s.split(' ').rev() { ... }

Here's how I tried to manually find rev() after realizing it was there (copied from reddit):

• Std docs -> str -> StrPrelude
• click CharSplits in split
• click Iterator...am back where I started
• go back to CharSplits
• click DoubleEndedIterator
• Don't see it...
• ah, search rev...it's in DoubleEndedIteratorExts
• back to iterator
• click trait DoubleEndedIteratorExts

A solution would be to include the methods each trait provides on the page. Or to have the trait list it's provided methods directly.

[tomjakubowski]

A solution would be to include the methods each trait provides on the page. Or to have the trait list it's provided methods directly.

I think what you're asking for here is for types which satisfy some blanket impl (like impl<A, I: DoubleEndedIterator<A>> DoubleEndedIteratorExt<A> for I) to include methods available on that trait: in this case listing DoubleEndedIteratorExt methods on types which implement DoubleEndedIterator due to the blanket impl. There's already an issue for this here: #19394

[tomjakubowski]

Also, in this case where you already know the name of a method, it would be faster even once #19394 is fixed to just search for rev and find it in the results. The blanket impl problem is really bad for discoverability though.

[mdinger]

Yeah, they're the same.

[gsingh93]

I'd like to see this worked on before 1.0.

[tomjakubowski]

See my comment here #19394 (comment)

[kornelski]

Similar problem: documentation for iterator types doesn't say how to create an instance of such iterator.

It's easy to stumble from search upon iterator implementation's documentation page, but these pages are useless: most methods they list are only internal iterator implementation boilerplate that isn't used directly.

e.g.

https://doc.rust-lang.org/std/slice/struct.ChunksMut.html

Doesn't tell how me to actually iterate over a thing!

1. I need to know that this page is incomplete
2. I need to know that a function I'm looking for is going to be on some other type, and I need to guess what type is that
3. Then I need to guess/find a function that returns this iterator (I guess there's chunks_iter_mut or something) on another page of documentation

[tomjakubowski]

That's a general problem (how do I produce something of this type, or something parametrized by this type) that I think needs a Hoogle-like solution (I'm aware of the existing GH issue).

—
Sent from Mailbox

On Sat, May 16, 2015 at 3:47 AM, Kornel notifications@github.com wrote:

Similar problem: documentation for iterator types doesn't say how to create an instance of such iterator.
It's easy to stumble from search upon iterator implementation's documentation page, but these pages are useless: most methods they list are only internal iterator implementation boilerplate that isn't used directly.
e.g.
https://doc.rust-lang.org/std/slice/struct.ChunksMut.html
Doesn't tell how me to actually iterate over a thing!

1. I need to know that this page is incomplete
2. I need to know that a function I'm looking for is going to be on some other type, and I need to guess what type is that

3. Then I need to guess/find a function that returns this iterator (I guess there's chunks_iter_mut or something) on another page of documentation

Reply to this email directly or view it on GitHub:
#19956 (comment)

[gsingh93]

The iterator problem is a bit different than the general problem, because with most other objects the methods to create them are defined in the struct impl itself. With iterator structs, they're intended to be created by methods in other struct impls, which is what makes them hard to find.

[tomjakubowski]

I disagree. When working on the compiler or rustdoc, for example, you often need to get an instance of some type out of a cache stored in the private field of a context struct somewhere, usually by calling a free function. Many of my efforts in rustdoc were stymied because while I knew I needed something of type Foo (or worse, a type parametrized by Foo), I didn't have an effective way to pare down the enormous search space of rustc's free functions by their return type (grepping the source was sometimes helpful, but the point of a documentation tool is to bring stuff like that at hand.) The same problem is there for iterator structs. 

—
Sent from Mailbox

On Sat, May 16, 2015 at 10:31 AM, Gulshan Singh notifications@github.com
wrote:

The iterator problem is a bit different than the general problem, because with most other objects the methods to create them are defined the struct impl itself. With iterator structs, they're intended to be created by methods in other struct impls, which is what makes them confusing.

Reply to this email directly or view it on GitHub:
#19956 (comment)

[gsingh93]

That is true (I ran into a similar problem with syntax extensions), but iterator structs are probably the most common case where this occurs and are more applicable to the average user. But in any case, Hoogle style search does solve this problem, and rustdoc actually supports this even though it isn't documented when pressing ?.

[bluss]

The original bug is "fixed". Maybe this bug can be closed & file new issues for new specific problems.

str docs are now all on one page, for the primitive type. Splits docs now show .rev() as one of the methods.

[mdinger]

I agree. Pushing the other issues to other bugs would also be a good idea.