From 5e1ccd414f400b46846853928041199a385fafc8 Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Wed, 10 Jan 2018 11:31:44 +0530 Subject: [PATCH] Clarify disambiguation rules --- text/1946-intra-rustdoc-links.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/text/1946-intra-rustdoc-links.md b/text/1946-intra-rustdoc-links.md index 530ec0ddd4a..914cdfbbf79 100644 --- a/text/1946-intra-rustdoc-links.md +++ b/text/1946-intra-rustdoc-links.md @@ -284,11 +284,14 @@ 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: +- 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. + Non-disambiguated paths cannot be used to link to macros. +- Links to types can be disambiguated by prefixing them 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 `, @@ -298,10 +301,10 @@ Our proposal is this: - Links to modules can be prefixed with `mod `, e.g., `See [mod@foo]`. - In links to macros, - the link label must end with a `!`, + 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, +- For disambiguating links to values, we differentiate three cases: + - Links to functions can be 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].` @@ -317,7 +320,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