rustdoc's for str are unclear

[brson]

As reported https://www.reddit.com/r/rust/comments/2xggd2/where_are_the_docs_for_str/

"I'd like to create a program that works with strings.

However, I could not find any documentation that described what functions I could call on str or string. Example:

http://doc.rust-lang.org/std/str/

The rust documentation for str defines Structs, Enums, Traits and 3 Functions.

So... I'm lost. This isn't like any documentation for any other language I'm familiar with. For example, when I view the java documentation for String I get a list of every method I can call on the String.

I can not find such a list for str.

Let's say I want to search a str or run a regex against it.

I looked in the Searcher trait, but there are no useful methods/functions for searching that I could see. The trait description is: This trait provides methods for searching for non-overlapping matches of a pattern starting from the front (left) of a string.

I see no way to define a pattern or even search.

I'm obviously totally missing it. Please help."

A good starting point might be to copy the text from http://doc.rust-lang.org/std/primitive.str.html into it, link explicitly to StrExt, and explain what StrExt is.

[nagisa]

I got hit by this so often too until I learnt that there’s a link to the primitive on the front page (/std/), because primitives aren’t very clearly marked in the search results.

[ghost]

Sorry to complicate a straightforward issue, but the Primitive str docs list trait implementations (and relevant examples/explanations) that aren't listed in the std::str docs. I include the link to StrExt and have a quick explanation of why it exists. My question is should I find a way to list those traits and examples in the std::str module as well, or include a link to the primitive (or both.)

Pros to providing links to both the primitive as well as StrExt instead of including primitive information in the module doc is that it allows very clear and intuitive rhetoric where you can directly reference the primitive and StrExt as two sides of the same coin. The downside is that we then have 3 places where information about str exists.

If we find a way to include the trait implementations in the module docs then it consolidates things in one place, empowering Ctrl+F. However it doesn't really reflect the organization of the code itself. Plus, I'm not sure rustdoc has the ability to do that, which would kind of decide it anyway.

Yay reading way too much into the line "copy the text from http://doc.rust-lang.org/std/primitive.str.html into it."

[nagisa]

std::str is a module and it should not contain any mention of implemented traits or anything like that. I’m honestly not sure whether we need to do anything else other than adding something like

See the primitive str type to see API it implements.

to the module documentation.

cc @steveklabnik

P.S. no, rustdoc does not allow adding a list of implemented traits to the module page. You can’t implement traits for modules after all.

[ghost]

Cool, sounds good. Just wanted to make sure it was clear before I pushed a 2 line fix and got some strange stares.