rustdoc: Semantically disambiguate impls and associated impl items rather than using numeric suffixes

[camelid]

Problem

Links to impls and their associated items are currently unstable in the sense that the addition of other items causes pre-existing items to have different URL fragments. This is because the URL fragments are only disambiguated by suffixing a number. If more items are added, the suffix changes. In addition, the suffix is not very human-understandable; it's hard to know which suffix will be chosen by rustdoc.

Proposed changes

• Instead of generating #impl, #impl-1, etc., generate IDs like #impl-Add<&str>-for-String (or similar).
• Prefix associated impl items (e.g., methods) with the ID of their impl.
• [Maybe:] Prefix namespaced Markdown headings within methods with the impl ID as well.

Concerns and unresolved questions

• Longer URL fragments will increase HTML page size. Will gzip compression mitigate this increased raw size?

[pierwill]

I'm interested in working on this, but I might not be able to get to it for a few weeks. If someone else is interested in taking this on, feel free to ping me here. :) In the meantime, @rustbot claim

[pierwill]

Is this the relevant code, @camelid?

https://github.com/rust-lang/rust/blob/ec59f5aa3c4adf43089d57b17bf42775b89bb710/src/librustdoc/html/format.rs#L991-L1023

(I've never worked on rustdoc before, so this should be fun!)

[camelid]

Hmm, I don't think that's it. I think the relevant code is at the top of render_impl_summary:

    let id = cx.derive_id(match i.inner_impl().trait_ {
        Some(ref t) => {
            if is_on_foreign_type {
                get_id_for_impl_on_foreign_type(&i.inner_impl().for_, t, cx)
            } else {
                format!("impl-{}", small_url_encode(format!("{:#}", t.print(cx))))
            }
        }
        None => "impl".to_string(),
    });

though there's also get_id_for_impl_on_foreign_type, which uses a form of semantic disambiguation that you may want to re-use.

The cx.derive_id() part, when applied to "impl", will return "impl" the first time, then "impl-1", "impl-2", etc.

[pierwill]

Could we do something as naive as this, as a starting point?

     aliases: &[String],
 ) {
     let id = cx.derive_id(match i.inner_impl().trait_ {
-        Some(ref t) => {
-            if is_on_foreign_type {
-                get_id_for_impl_on_foreign_type(&i.inner_impl().for_, t, cx)
-            } else {
-                format!("impl-{}", small_url_encode(format!("{:#}", t.print(cx))))
-            }
-        }
+        Some(ref t) => get_id_for_impl(&i.inner_impl().for_, t, cx),
         None => "impl".to_string(),
     });
     let aliases = if aliases.is_empty() {
@@ -2194,7 +2188,7 @@ fn sidebar_struct(cx: &Context<'_>, buf: &mut Buffer, it: &clean::Item, s: &clea
     }
 }
 
-fn get_id_for_impl_on_foreign_type(
+fn get_id_for_impl(
     for_: &clean::Type,
     trait_: &clean::Path,
     cx: &Context<'_>,
@@ -2210,7 +2204,7 @@ fn extract_for_impl_name(item: &clean::Item, cx: &Context<'_>) -> Option<(String
                 // so this parameter does nothing.
                 (
                     format!("{:#}", i.for_.print(cx)),
-                    get_id_for_impl_on_foreign_type(&i.for_, trait_, cx),
+                    get_id_for_impl(&i.for_, trait_, cx),
                 )
             })
         }

Except we do want to know about foreign types, still...

[camelid]

Could we do something as naive as this, as a starting point?

Perhaps. It's hard to know without seeing the results.

Except we do want to know about foreign types, still...

I'm not sure I understand what you mean.

[pierwill]

I'm afraid I'm too far removed from this code now to see this across the finish line...

[pierwill]

@GuillaumeGomez : Can this be closed now that #98939 is merged?

[GuillaumeGomez]

It can indeed! Thanks for notifying.