Merge pull request #2285 from Manishearth/intra-rustdoc-links-update

Update the disambiguation handling in RFC 1946 (intra-rustdoc-links) to match impl concerns

Author: Manishearth

text/1946-intra-rustdoc-links.md

@@ -284,29 +284,51 @@ To be able to link to each item,
 we'll need a way to disambiguate the namespaces.
 Our proposal is this:
 
-- Links to types are written as described earlier,
-  with no pre- or suffix,
-  e.g., `Look at the [FOO] trait`.
-  For consistency,
-  it is also possible to prefix the type with the concrete item type:
-  - Links to `struct`s can be prefixed with `struct `,
-    e.g., `See [struct Foo]`.
-  - Links to `enum`s can be prefixed with `enum `,
-    e.g., `See [enum foo]`.
-  - Links to type aliases can be prefixed with `type `,
-    e.g., `See [type foo]`.
-  - Links to modules can be prefixed with `mod `,
-    e.g., `See [mod foo]`.
+- In unambiguous cases paths can be written as described earlier,
+  with no pre- or suffix, e.g., `Look at the [FOO] trait`. This also
+  applies to modules and tuple structs which exist in both namespaces.
+  Rustdoc will throw an error if you use a non-disambiguated path in
+  the case of there being a value in both the type and value namespace.
+- Links to types can be disambiguated by prefixing them with the concrete
+  item type:
+  - Links to any type-namespace object can be prefixed with `type@`,
+    e.g., `See [type@foo]`. This will work for structs, enums, mods, traits,
+    and unions.
+  - Links to `struct`s can be prefixed with `struct@`,
+    e.g., `See [struct@Foo]`.
+  - Links to `enum`s can be prefixed with `enum@`,
+    e.g., `See [enum@foo]`.
+  - Links to modules can be prefixed with `mod@`,
+    e.g., `See [mod@foo]`.
+  - Links to traits can be prefixed with `trait@`,
+    e.g., `See [trait@foo]`.
+  - Links to unions can be prefixed with `union@`,
+    e.g., `See [union@foo]`.
+  - It is possible that disambiguators for one kind of type-namespace object
+    will work for the other (i.e. you can use `struct@` to refer to an enum),
+    but do not rely on this.
+- Modules exist in both the type and value namespace and can be disambiguated
+  with a `mod@` or `module@`, e.g. `[module@foo]`
 - In links to macros,
-  the link label must end with a `!`,
-  e.g., `Look at the [FOO!] macro`.
-- For links to values, we differentiate three cases:
-  - Links to functions are written with a `()` suffix,
-    e.g., `Also see the [foo()] function`.
-  - Links to constants are prefixed with `const `,
-    e.g., `As defined in [const FOO].`
-  - Links to statics are prefixed with `static `,
-    e.g., `See [static FOO]`.
+  the link label can end with a `!`,
+  e.g., `Look at the [FOO!] macro`. You can alternatively use a `macro@` prefix,
+  e.g. `[macro@foo]`
+- For disambiguating links to values, we differentiate three cases:
+  - Links to any kind of value (function, const, static) can be prefixed with `value@`,
+    e.g., `See [value@foo]`.
+  - Links to functions and methods can be written with a `()` suffix,
+    e.g., `Also see the [foo()] function`. You can also use `function@`, `fn@`,
+    or `method@`.
+  - Links to constants are prefixed with `const@`,
+    e.g., `As defined in [const@FOO].`
+  - Links to statics are prefixed with `static@`,
+    e.g., `See [static@FOO]`.
+  - It is possible that disambiguators for one kind of type-namespace object
+    will work for the other (i.e. you can use `static@` to refer to a const),
+
+For disambiguation markers using an `@`, in implied shortcut links
+you can use a space instead of the `@`. In other words, `[struct Foo]`
+is fine (and preferred).
 
 It should be noted that in the RFC discussion it was determined
 that exact knowledge of the item type
@@ -317,7 +339,6 @@ with the wrong prefix that is in the same namespace.
 E.g., given an `struct Foo`, it may be possible to link to it using `[enum Foo]`,
 or, given a `mod bar`, it may be possible to link to that using `[struct bar]`.
 
-
 ## Errors
 [errors]: #errors