intra-doc links to modules instead of primitives inside standard library #58699
Comments
jonas-schievink
added
T-rustdoc
|
Therefore we should try to link to types before modules I assume? I'll see how it comes out. |
|
Yes I think types should go before modules. After all it's always possible to use |
|
Oh btw, you can force the resolution by adding the type before hand like |
|
It comes from the compiler directly. We need to re-order how the items are resolved. cc @rust-lang/compiler |
|
@GuillaumeGomez an alternative is to resolve in an empty module first and only then resolve in the current scope. This ambiguity is only possible for primitives, any other types will give a multiple definition error: https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=16d8de614c51403e2f8576f355ed6f9c. Since primitives are always in scope they will be the only thing in scope in the empty module (assuming there's no |
Previously, if there were a module in scope with the same name as the primitive, that would take precedence. Coupled with rust-lang#58699, this made it impossible to link to the primitive when that module was in scope. This approach could be extended so that `struct@foo` would no longer resolve to any type, etc. However, it could not be used for glob imports: ```rust pub mod foo { pub struct Bar; } pub enum Bar {} use foo::*; // This is expected to link to `inner::Bar`, but instead it will link to the enum. /// Link to [struct@Bar] pub struct MyDocs; ``` The reason for this is that this change does not affect the resolution algorithm of rustc_resolve at all. The only reason we could special-case primitives is because we have a list of all possible primitives ahead of time.
Always resolve type@primitive as a primitive, not a module Previously, if there were a module in scope with the same name as the primitive, that would take precedence. Coupled with rust-lang#58699, this made it impossible to link to the primitive when that module was in scope. This approach could be extended so that `struct@foo` would no longer resolve to any type, etc. However, it could not be used for glob imports: ```rust pub mod foo { pub struct Bar; } pub enum Bar {} use foo::*; // This is expected to link to `inner::Bar`, but instead it will link to the enum. /// Link to [struct@Bar] pub struct MyDocs; ``` The reason for this is that this change does not affect the resolution algorithm of rustc_resolve at all. The only reason we could special-case primitives is because we have a list of all possible primitives ahead of time. Closes rust-lang#74063 r? @Manishearth
Always resolve type@primitive as a primitive, not a module Previously, if there were a module in scope with the same name as the primitive, that would take precedence. Coupled with rust-lang#58699, this made it impossible to link to the primitive when that module was in scope. This approach could be extended so that `struct@foo` would no longer resolve to any type, etc. However, it could not be used for glob imports: ```rust pub mod foo { pub struct Bar; } pub enum Bar {} use foo::*; // This is expected to link to `inner::Bar`, but instead it will link to the enum. /// Link to [struct@Bar] pub struct MyDocs; ``` The reason for this is that this change does not affect the resolution algorithm of rustc_resolve at all. The only reason we could special-case primitives is because we have a list of all possible primitives ahead of time. Closes rust-lang#74063 r? @Manishearth
Always resolve type@primitive as a primitive, not a module Previously, if there were a module in scope with the same name as the primitive, that would take precedence. Coupled with rust-lang#58699, this made it impossible to link to the primitive when that module was in scope. This approach could be extended so that `struct@foo` would no longer resolve to any type, etc. However, it could not be used for glob imports: ```rust pub mod foo { pub struct Bar; } pub enum Bar {} use foo::*; // This is expected to link to `inner::Bar`, but instead it will link to the enum. /// Link to [struct@Bar] pub struct MyDocs; ``` The reason for this is that this change does not affect the resolution algorithm of rustc_resolve at all. The only reason we could special-case primitives is because we have a list of all possible primitives ahead of time. Closes rust-lang#74063 r? @Manishearth
Always resolve type@primitive as a primitive, not a module Previously, if there were a module in scope with the same name as the primitive, that would take precedence. Coupled with rust-lang#58699, this made it impossible to link to the primitive when that module was in scope. This approach could be extended so that `struct@foo` would no longer resolve to any type, etc. However, it could not be used for glob imports: ```rust pub mod foo { pub struct Bar; } pub enum Bar {} use foo::*; // This is expected to link to `inner::Bar`, but instead it will link to the enum. /// Link to [struct@Bar] pub struct MyDocs; ``` The reason for this is that this change does not affect the resolution algorithm of rustc_resolve at all. The only reason we could special-case primitives is because we have a list of all possible primitives ahead of time. Closes rust-lang#74063 r? @Manishearth
Always resolve type@primitive as a primitive, not a module Previously, if there were a module in scope with the same name as the primitive, that would take precedence. Coupled with rust-lang#58699, this made it impossible to link to the primitive when that module was in scope. This approach could be extended so that `struct@foo` would no longer resolve to any type, etc. However, it could not be used for glob imports: ```rust pub mod foo { pub struct Bar; } pub enum Bar {} use foo::*; // This is expected to link to `inner::Bar`, but instead it will link to the enum. /// Link to [struct@Bar] pub struct MyDocs; ``` The reason for this is that this change does not affect the resolution algorithm of rustc_resolve at all. The only reason we could special-case primitives is because we have a list of all possible primitives ahead of time. Closes rust-lang#74063 r? @Manishearth
Originally posted by @Manishearth in #74063 (comment) @Manishearth is this still your opinion? That would mean closing this issue as wontfix, but I'm not convinced that's the most clear behavior. |
|
@jyn514 Well, I would close this as fixed, but yes. I think this is a pretty rare situation to be in and the current behavior is not incorrect, it's just surprising, but "fixing" it would also make it surprising to another group. |
|
@Manishearth and I discussed this again and decided it would be less surprising than the current behavior (@Manishearth himself made the same mistake in #74470!) So I plan to implement this sometime soon. |
For example in the doc for
str::len:The
charin the doc links to char/index.html instead of primitive.char.html.Outside of the standard library,
charlinks to the primitive, unless there is ause std::char;statement in which case it links to the module.The text was updated successfully, but these errors were encountered: