Rust documentation does not document interaction between modules, scopes, and traits

[arienmalec]

Per issue #7643, methods implemented on traits are only searched when the trait can be searched in "scope". Per the close of issue #21049, that search "scope" is more narrowly defined: method search on implemented traits is only for traits that can be referenced without a module path. That is to say, a method defined as an implementation on a trait that can be referenced astraits::Foo will not be found, whereas the same method will be found if the trait can be referenced as Foo (see the example program in #21049.

This behavior is inconsistent with documentation. For example, the reference documentation 6.1.9 (http://doc.rust-lang.org/reference.html#traits) states "All values that have implementations of this trait in scope can have their draw and bounding_box methods called, using value.bounding_box() syntax." implying that what matters is that the impl is reachable, whereas the compiler also demands that the trait be reachable.

The close of issue #21049 implies that there's a different definition of "scope" for traits; again, what seems to matter is that the trait be reachable without module qualification (again, as bare Foo rather than through traits::Foo). This requires use statements that import the name without qualification (use traits::Foo; or use traits::{Foo,Bar,Baz}; rather than use statements that merely bring the module into scope (use traits;). This behavior does not seem to be documented.

Outside of reference documentation, in the book and rustbyexample material it would be useful to document examples of this behavior in the documentation of traits.

Finally, existing examples that implement traits should be changed to bring the trait into scope without module qualification. For example, the examples for implementing std::fmt::Show and std::fmt::String generally do so through a use std::fmt; statement, requiring reference as fmt::String. Fortunately, this example seems to work, either because the standard library follows different rules for trait method search, or because the fmt method implemented is called in a different way. Despite the fact that it works, it's confusing, because that approach will not work in other contexts.

This brings up a different issue: because of the trait method reference rules, a trait shouldn't be named any name that is already imported without qualification - String is therefore a bad trait name.

I'd be happy to take a hand at cleaning up documentation, but I'll admit that I don't understand the way this should work (as indicated by my original bug report, I would assume that methods for implemented traits should be found so long as both the underlying trait and implementation are reachable in scope, whether module qualified or not).

[steveklabnik]

The reference is going to be very off on things like this, yes. We should get that fixed up.

[steveklabnik]

This is a specific part of #16676, so I'm giving it a close, and we'll make sure to address it as part of that.