Remove intra-doc link disambiguation prefix aliases #77277

chris-morgan · 2020-09-27T20:28:23Z

(That title is gnarly!)

Read the commit messages for details and remaining questions about the method and constant aliases. rust-lang/rfcs#2988 is relevant to this consideration.

/cc @jyn514

“Prim” is rustc jargon; everywhere else uses the normal English word “primitive”, including the file names like primitive.u8.html, which it’s nice to match. This only touches the `prim@` disambiguation prefix. rustc still refers to “prim” internally in some places, but being an outsider to rustc I’m unqualified to judge whether any change is called for there. (The uses are: PrimIntCast/prim-int-cast; PrimTy, short for PrimitiveType; and an identifier prim, most commonly of type PrimitiveType.)

Following on from what I think should be the fairly uncontroversial killing of the prim@ disambiguation prefix in favour of primitive@, we have a few more aliases that it may be worth evicting from rustdoc. - `function` is removed in favour of `fn`, which matches the keyword and the fn.*.html filenames. - `module` is removed in favour of `mod`, which matches the keyword. Modules become folders, so there’s no filename argument. I have kept two aliases at this time because I think more discussion is called for: - `method` is retained as an alias of `fn`; it matches the method.* fragment that methods are given. Well, unless they’re tymethod.*. Should tymethod therefore be allowed as an alias? As I say, discussion is called for. Also, subjectively people may prefer to call a thing a method than a function, though that argument could be applied to retaining the “function” and “module” spellings. - `constant` is retained as an alias of `const`; their filenames are currently of the form constant.*.html.

jyn514 · 2020-09-27T20:39:46Z

r? @jyn514

jyn514

function is removed in favour of fn, which matches the keyword

module is removed in favour of mod, which matches the keyword.

👍

constant is retained as an alias of const; their filenames are
currently of the form constant.*.html.

I don't think we need to be consistent with rustdoc file names, they're not really user-facing. const seems fine to me (constant was only added recently: #74430 (comment)). Actually it looks like it was never even documented.

method is retained as an alias of fn; it matches the method.*
fragment that methods are given.

Hmm, I'm again not sure we should keep this ... Rust doesn't have methods, it has functions. The only thing that &self does is let you use the self.f() syntax in addition to normal Self::f(&self).

cc @rust-lang/rustdoc

jyn514 · 2020-09-27T20:53:10Z

src/librustdoc/passes/collect_intra_doc_links.rs

                "derive" => Kind(DefKind::Macro(MacroKind::Derive)),
                "type" => NS(Namespace::TypeNS),
                "value" => NS(Namespace::ValueNS),
                "macro" => NS(Namespace::MacroNS),
-                "prim" | "primitive" => Primitive,
+                "primitive" => Primitive,


Can you also add a help message if someone tries to use the old names? I'd implement it something like this:

Add a new ResolutionError::UnsupportedDisambiguator variant

Return the variant if someone tries to use the old names (and change the error type of the function to ResolutionFailure):

Suggested change

"primitive" => Primitive,

"primitive" => Primitive,

"module" | "function" | "prim" => return Err(ResolutionError::UnsupportedDisambiguator(prefix)),

Change fn resolution_failure to give a helpful error, something like

warning: unresolved link to `prim@char` --> bad.rs:1:6 | 1 | //! [prim@char] | ^^^^^^^^^ help: use `primitive` instead of `prim`: `primitive@char` | = note: the `prim` disambiguator has been removed, see #77277

There are examples in that function, but feel free to ask for help if you need it.

I can do this, but I’m a little surprised you’d suggest it: this is niche, previously-unstable functionality, and it wouldn’t surprise me if literally no one has used these aliases.

The problem with that reasoning is that people aren't using it as if it's unstable. module@ does not seem particularly niche to me and neither does function@. Part of the reason I've been trying to stabilize intra-doc links is because people are treating it as if it's stable, because docs.rs uses the nightly compiler.

This is part of a larger discussion I want to have about rustdoc and nightly: rustdoc should be enforcing feature gates. Right now people don't know what's stable and what's unstable because very few people document locally, and those that do mostly use nightly and think everything must be fine on stable because they haven't added #![feature].

I meant the disambiguation prefixes, which I think it’s fair to say are niche; I had forgotten that intra-doc links as a whole were only now becoming stable!

I had forgotten that intra-doc links as a whole were only now becoming stable!

Right, this is what I mean by rustdoc should enforce feature gates. See also #63305.

I meant the disambiguation prefixes, which I think it’s fair to say are niche

Well, either way I don't think we should remove functionality without pointing to how to fix this code. So I'd strongly prefer to add this help message.

jyn514 · 2020-09-27T20:54:59Z

rust-lang/rfcs#2988 is relevant to this consideration.

I'm curious why you think so, in my mind they're entirely separate.

chris-morgan · 2020-09-28T12:10:55Z

RFC 2988 is relevant because I like having the prefixes match the filenames (especially when it’s hijacking link hrefs), which is also why I haven’t pulled constant out already. It’s not a big deal either way, I’d be content to remove the two further aliases.

But really, I just like consistency. You say rustdoc URLs aren’t user-facing, but I strongly disagree—and in fact I’d say that a large part of the purpose of RFC 2988 is that they are user-facing to at least some degree, even if you think that the precise spelling of the URLs shouldn’t be. But I manually type rustdoc URLs moderately regularly (more regularly than I would need to if I arranged better tooling for myself!).

Manishearth · 2020-09-28T14:27:04Z

I do not think we should remove method. They are all conceptually functions, but people do not know that!

I think removing prim makes sense, but there are multiple aliases where we have both the name of the thing and the shortform used as a keyword (fn vs function, const vs constant)

There is no cost to having these extra, they just make it less likely for people to go "what was the disambiguator again?".

jyn514 · 2020-09-28T14:38:45Z

I don't have strong opinions either way on this, I'll defer to @Manishearth's judgement.

bors · 2020-10-01T01:40:25Z

☔ The latest upstream changes (presumably #76325) made this pull request unmergeable. Please resolve the merge conflicts.

Note that reviewers usually do not review pull requests until merge conflicts are resolved! Once you resolve the conflicts, you should change the labels applied by bors to indicate that your PR is ready for review. Post this as a comment to change the labels:

@rustbot modify labels: +S-waiting-on-review -S-waiting-on-author

camelid · 2020-10-16T21:27:15Z

This is a breaking change though since intra-doc links are stable on beta, right?

Manishearth · 2020-10-17T15:48:53Z

We're allowed to break beta, but yes, if this wants to land it should be soon. I am against removing things other than prim though.

Dylan-DPC-zz · 2020-11-03T16:41:35Z

@chris-morgan any updates on this?

library/std/src/primitive_docs.rs

src/test/rustdoc-ui/intra-link-prim-conflict.rs

jyn514 · 2020-11-12T05:17:33Z

Intra-doc links will be stable in a week, so I don't think it makes sense to change this at this point.

chris-morgan added 2 commits September 28, 2020 01:48

This comment has been minimized.

Sign in to view

rust-highfive assigned sfackler Sep 27, 2020

This comment has been minimized.

Sign in to view

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 27, 2020

rust-highfive assigned jyn514 and unassigned sfackler Sep 27, 2020

jyn514 added A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Sep 27, 2020

jyn514 reviewed Sep 27, 2020

View reviewed changes

jyn514 added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 5, 2020

jyn514 mentioned this pull request Oct 16, 2020

Tracking issue for check_invalid_html_tags #67799

Closed

5 tasks

ghost reviewed Nov 8, 2020

View reviewed changes

library/std/src/primitive_docs.rs Show resolved Hide resolved

ghost reviewed Nov 8, 2020

View reviewed changes

src/test/rustdoc-ui/intra-link-prim-conflict.rs Show resolved Hide resolved

jyn514 closed this Nov 12, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Remove intra-doc link disambiguation prefix aliases #77277

Remove intra-doc link disambiguation prefix aliases #77277

chris-morgan commented Sep 27, 2020

This comment has been minimized.

This comment has been minimized.

jyn514 commented Sep 27, 2020

jyn514 left a comment •

edited

Loading

jyn514 Sep 27, 2020 •

edited

Loading

chris-morgan Sep 28, 2020

jyn514 Sep 28, 2020

chris-morgan Sep 28, 2020

jyn514 Sep 28, 2020

jyn514 commented Sep 27, 2020

chris-morgan commented Sep 28, 2020

Manishearth commented Sep 28, 2020

jyn514 commented Sep 28, 2020

bors commented Oct 1, 2020

camelid commented Oct 16, 2020

Manishearth commented Oct 17, 2020

Dylan-DPC-zz commented Nov 3, 2020

jyn514 commented Nov 12, 2020

	"primitive" => Primitive,
	"primitive" => Primitive,
	"module" \| "function" \| "prim" => return Err(ResolutionError::UnsupportedDisambiguator(prefix)),

Remove intra-doc link disambiguation prefix aliases #77277

Remove intra-doc link disambiguation prefix aliases #77277

Conversation

chris-morgan commented Sep 27, 2020

This comment has been minimized.

This comment has been minimized.

jyn514 commented Sep 27, 2020

jyn514 left a comment • edited Loading

Choose a reason for hiding this comment

jyn514 Sep 27, 2020 • edited Loading

Choose a reason for hiding this comment

chris-morgan Sep 28, 2020

Choose a reason for hiding this comment

jyn514 Sep 28, 2020

Choose a reason for hiding this comment

chris-morgan Sep 28, 2020

Choose a reason for hiding this comment

jyn514 Sep 28, 2020

Choose a reason for hiding this comment

jyn514 commented Sep 27, 2020

chris-morgan commented Sep 28, 2020

Manishearth commented Sep 28, 2020

jyn514 commented Sep 28, 2020

bors commented Oct 1, 2020

camelid commented Oct 16, 2020

Manishearth commented Oct 17, 2020

Dylan-DPC-zz commented Nov 3, 2020

jyn514 commented Nov 12, 2020

jyn514 left a comment •

edited

Loading

jyn514 Sep 27, 2020 •

edited

Loading