Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 6 commits into from
Mar 8, 2018
Merged

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

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
be38090
Use @ symbol in path ambiguity markers
Manishearth Jan 10, 2018
8f5be35
Clarify disambiguation rules
Manishearth Jan 10, 2018
9eccc58
add trait@, union@, value@, macro@
Manishearth Jan 19, 2018
f231d75
Allow ambiguous macros
Manishearth Jan 19, 2018
ee53b90
allow function@
Manishearth Jan 19, 2018
0b17ddf
Add more disambiguators to match PR
Manishearth Jan 19, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 27 additions & 21 deletions text/1946-intra-rustdoc-links.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -284,29 +284,36 @@ 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,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

iirc we discussed this in the original RFC and decided against it? I can't remember why though. One possible reason is forwards-compatability - adding a name to a namespace would break any docs that don't use a disambiguator.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can convert the error into a warning to make it a non-breaking change.

However, you already have this forwardcompat hazard with regular links. [foo](bar) is still a valid link; just won't point anywhere; usually.

You also can already break docs within this proposal by changing your imports in the file.

We provide disambiguation markers for folks who wish to catch this, and I think not mandating the disambiguation markers will make it easy to conveniently write docs. Clashing namespaces is not a common thing to do (aside from the implicit clashes introduced by tuple structs -- we handle this already), and when you do clash them usually it's to create a constructor for the same type so nbd.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why not?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's what the current impl is, this amendment matches the impl. That can be changed.

- 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]`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we use the @ in the link target but allow the space when using implied ref links?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but I prefer uniformity here. Wonder what others think.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, I like your idea better. Hm.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(I actually wrote the implementation with that in mind when i switched it to use @ >_>)

- 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]`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess unions and traits should be in this list too?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

- In links to macros,
the link label must end with a `!`,
the link label _must_ end with a `!`,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't looked this up, but I'm pretty sure I argued strongly against this in the original RFC and I'm surprised to see it here. The ! is the syntax for calling a macro, not naming it (analogous to () to call a function), so I think rustdoc should not include the ! as part of the name (this is more important with macros 2.0 where you import the macro in a use statement without using !). Also, this doesn't make sense for attribute-like macros which are not even used with a !.

So, I would like to see macros named using just the name, and if disambiguation is necessary, to use macro@. I don't mind if you want to allow ! as a shorthand, but I would prefer not to.

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].`
- Links to statics are prefixed with `static `,
e.g., `See [static FOO]`.
- 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]`.

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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should note that you don't need to use the data type names - using type@ and value@ should be OK for all types and values, respectively.


It should be noted that in the RFC discussion it was determined
that exact knowledge of the item type
Expand All @@ -317,7 +324,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

Expand Down