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

Manishearth · 2018-01-10T06:03:55Z

In rust-lang/rust#47046, we realized that the proposed disambiguation syntax is not valid CommonMark, and changed it to [struct@Foo], etc.

Additionally, we feel that you should be allowed to use un-disambiguated paths to refer to values as long as there isn't a clash.

cc @QuietMisdreavus @killercup

Manishearth · 2018-01-10T06:05:04Z

AFAICT this doesn't need to go through the full RFC process, just a quick discussion and perhaps fcp.

sfackler · 2018-01-10T06:06:10Z

text/1946-intra-rustdoc-links.md

@@ -317,6 +320,7 @@ 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]`.

+In case a type is in 


Dangling line?

my bad, was initially going to expand there and then decided to take a different path. removed.

est31 · 2018-01-10T06:07:14Z

@Manishearth awesome PR, fewest RFCs get corrected if it is decided that some other path should be taken.

killercup

Thanks! <3

killercup · 2018-01-10T06:33:46Z

text/1946-intra-rustdoc-links.md

  - Links to `struct`s can be prefixed with `struct `,
-    e.g., `See [struct Foo]`.
+    e.g., `See [struct@Foo]`.


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

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

Actually, I like your idea better. Hm.

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

kennytm · 2018-01-10T10:40:32Z

Apparently, links with spaces in them don't work in commonmark at all.

Interestingly escaping the space like struct\ Foo does work (and the URL is encoded as %5C%20 😒)

In this crate we would like to link to:

* [`ThisType`](struct\ ::ThisType)
* [`ThisEnum`](enum\ ::ThisEnum)
* [`ThisTrait`](trait\ ::ThisTrait)
* [`ThisAlias`](type\ ::ThisAlias)
* [`ThisUnion`](union\ ::ThisUnion)
* [`this_function`](::this_function())
* [`THIS_CONST`](const\ ::THIS_CONST)
* [`THIS_STATIC`](static\ ::THIS_STATIC)

<p>In this crate we would like to link to:</p>
<ul>
<li><a href="struct%5C%20::ThisType"><code>ThisType</code></a></li>
<li><a href="enum%5C%20::ThisEnum"><code>ThisEnum</code></a></li>
<li><a href="trait%5C%20::ThisTrait"><code>ThisTrait</code></a></li>
<li><a href="type%5C%20::ThisAlias"><code>ThisAlias</code></a></li>
<li><a href="union%5C%20::ThisUnion"><code>ThisUnion</code></a></li>
<li><a href="::this_function()"><code>this_function</code></a></li>
<li><a href="const%5C%20::THIS_CONST"><code>THIS_CONST</code></a></li>
<li><a href="static%5C%20::THIS_STATIC"><code>THIS_STATIC</code></a></li>
</ul>

QuietMisdreavus · 2018-01-10T15:53:15Z

text/1946-intra-rustdoc-links.md

+  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 `,


Since all these "can be prefixed with" notes include a space in their code span, i would like to see the @ in there as well. So this one would be:

Links to structs can be prefixed with struct@,

liigo · 2018-01-18T06:58:11Z

[struct.Foo] is better since the dot (.) don't requires you pressing the SHIFT key.

Manishearth · 2018-01-18T07:00:52Z

The problem is that struct.foo is more like a URL. We eventually want to detect and warn on broken intra links, and to do that you need to be sure that something was a broken intra link and not a URL. For this there should be a clear way of disambiguating, "optionally-backtick-surrounded identifier with possible at symbol or parentheses" doesn't clash with what most URLs will look like.

Manishearth · 2018-01-18T07:01:39Z

r? @rust-lang/dev-tools

nrc · 2018-01-19T05:09:19Z

@Fcpbot fcp merge

I'm not quite happy to merge, but I think we should start FCP now and discuss as we go since this is just an amendment to an existing RFC (discussed at dev-tools meeting today).

nrc · 2018-01-19T05:29:15Z

@rfcbot fcp merge

rfcbot · 2018-01-19T05:29:15Z

Team member @nrc has proposed to merge this. The next step is review by the rest of the tagged teams:

Concerns:

~~review comments~~ resolved by Update the disambiguation handling in RFC 1946 (intra-rustdoc-links) to match impl concerns #2285 (comment)

Once a majority of reviewers approve (and none object), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

nrc · 2018-01-19T05:38:45Z

text/1946-intra-rustdoc-links.md

+  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.


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

nrc · 2018-01-19T05:39:32Z

text/1946-intra-rustdoc-links.md

+
+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).


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.

nrc · 2018-01-19T05:54:00Z

text/1946-intra-rustdoc-links.md

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


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.

nrc · 2018-01-19T05:54:43Z

text/1946-intra-rustdoc-links.md

+  - 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]`.


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

nrc · 2018-01-19T05:56:11Z

text/1946-intra-rustdoc-links.md

-    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,


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.

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.

nrc · 2018-01-19T05:56:41Z

@rfcbot concern review comments

sophiajt · 2018-01-19T06:04:22Z

@nrc - I'm not on dev tools now, so I'm guessing my name should be removed?

Manishearth · 2018-01-19T06:33:17Z

The current impl e.g. allows you to use struct@ to refer to an enum, I'm not sure if we should spec this as always working or leave it implementation defined. I left a note making it implementation defined.

9eccc58

Manishearth · 2018-01-19T06:37:54Z

I've made a change (f231d75) allowing ambiguous references to macros. I mostly didn't do this because it was tricky to impl and I wanted something working, but this can be changed.

nrc · 2018-02-01T23:37:43Z

We discussed at the dev-tools meeting today, we clarified that this should be regarded as a 'bug fix' RFC and that there will be a chance to re-visit and discuss the design during a stabilisation period. Therefore we should tick off and land this quickly.

@rfcbot resolved review comments

@Manishearth thanks for the updates!

Manishearth · 2018-02-02T02:22:16Z

Oh, just a note, I also introduced method@ and variant@ in a fixup pr. I'll add that to the RFC before merging.

Manishearth · 2018-02-02T07:33:59Z

Updated.

Manishearth · 2018-02-26T21:04:58Z

(Updates on this? Stalled on review)

fitzgen · 2018-02-26T21:06:21Z

@rfcbot reviewed

(Sorry for delay!)

killercup · 2018-02-26T21:06:31Z

I'm (still) in favor of this! :)

@rfcbot reviewed

japaric · 2018-02-26T21:10:11Z

@rfcbot reviewed

rfcbot · 2018-02-26T21:10:13Z

🔔 This is now entering its final comment period, as per the review above. 🔔

rfcbot · 2018-03-08T21:18:32Z

The final comment period is now complete.

Use @ symbol in path ambiguity markers

be38090

This was referenced Jan 10, 2018

Implement RFC 1946 - intra-rustdoc links rust-lang/rust#47046

Merged

Intra Rustdoc Links #1946

Merged

Manishearth added the T-rustdoc Relevant to rustdoc team, which will review and decide on the RFC. label Jan 10, 2018

sfackler reviewed Jan 10, 2018

View reviewed changes

Manishearth force-pushed the intra-rustdoc-links-update branch from cb8206a to 5e1ccd4 Compare January 10, 2018 06:17

killercup reviewed Jan 10, 2018

View reviewed changes

QuietMisdreavus reviewed Jan 10, 2018

View reviewed changes

Manishearth force-pushed the intra-rustdoc-links-update branch from 5e1ccd4 to 0bad27d Compare January 10, 2018 16:08

Clarify disambiguation rules

8f5be35

Manishearth force-pushed the intra-rustdoc-links-update branch from 0bad27d to 8f5be35 Compare January 10, 2018 16:10

nrc added the T-dev-tools label Jan 18, 2018

rfcbot added the proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. label Jan 19, 2018

nrc reviewed Jan 19, 2018

View reviewed changes

add trait@, union@, value@, macro@

9eccc58

Manishearth force-pushed the intra-rustdoc-links-update branch from 46204f1 to 9eccc58 Compare January 19, 2018 06:31

Allow ambiguous macros

f231d75

allow function@

ee53b90

petrochenkov added T-dev-tools Relevant to the development tools team, which will review and decide on the RFC. and removed T-dev-tools labels Jan 30, 2018

Add more disambiguators to match PR

0b17ddf

Manishearth force-pushed the intra-rustdoc-links-update branch from cee1658 to 0b17ddf Compare February 2, 2018 07:33

rfcbot added final-comment-period Will be merged/postponed/closed in ~10 calendar days unless new substational objections are raised. and removed proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. labels Feb 26, 2018

Manishearth merged commit fd70ea3 into rust-lang:master Mar 8, 2018

Manishearth deleted the intra-rustdoc-links-update branch March 8, 2018 21:21

Manishearth mentioned this pull request Aug 20, 2020

Update the intra-doc link RFC to match the implementation #2975

Merged

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

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

Conversation

Manishearth commented Jan 10, 2018

Manishearth commented Jan 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

est31 commented Jan 10, 2018

killercup left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kennytm commented Jan 10, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liigo commented Jan 18, 2018

Manishearth commented Jan 18, 2018

Manishearth commented Jan 18, 2018

nrc commented Jan 19, 2018

nrc commented Jan 19, 2018

rfcbot commented Jan 19, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nrc commented Jan 19, 2018

sophiajt commented Jan 19, 2018

Manishearth commented Jan 19, 2018 • edited Loading

Manishearth commented Jan 19, 2018

nrc commented Feb 1, 2018

Manishearth commented Feb 2, 2018

Manishearth commented Feb 2, 2018

Manishearth commented Feb 26, 2018

fitzgen commented Feb 26, 2018

killercup commented Feb 26, 2018

japaric commented Feb 26, 2018

rfcbot commented Feb 26, 2018

rfcbot commented Mar 8, 2018

kennytm commented Jan 10, 2018 •

edited

Loading

rfcbot commented Jan 19, 2018 •

edited

Loading

Manishearth commented Jan 19, 2018 •

edited

Loading