rustdoc: improve rustdoc HTML suggestions handling of nested generics

src/librustdoc/passes/html_tags.rs

@@ -94,6 +94,34 @@ fn extract_path_backwards(text: &str, end_pos: usize) -> Option<usize> {
  if current_pos == end_pos { None } else { Some(current_pos) }
 }
 
+fn extract_path_forward(text: &str, start_pos: usize) -> Option<usize> {
+ use rustc_lexer::{is_id_continue, is_id_start};
+ let mut current_pos = start_pos;
+ loop {
+ if current_pos < text.len() && text[current_pos..].starts_with("::") {
+ current_pos += 2;
+ } else {
+ break;
+ }
+ let mut chars = text[current_pos..].chars();
+ if let Some(c) = chars.next() {
+ if is_id_start(c) {
+ current_pos += c.len_utf8();
+ } else {
+ break;
+ }
+ }
+ while let Some(c) = chars.next() {
+ if is_id_continue(c) {
+ current_pos += c.len_utf8();
+ } else {
+ break;
+ }
+ }
+ }
+ if current_pos == start_pos { None } else { Some(current_pos) }
+}
+
 fn is_valid_for_html_tag_name(c: char, is_empty: bool) -> bool {
  // https://spec.commonmark.org/0.30/#raw-html
  //
@@ -218,19 +246,68 @@ impl<'a, 'tcx> DocVisitor for InvalidHtmlTagsLinter<'a, 'tcx> {
  // If a tag looks like `<this>`, it might actually be a generic.
  // We don't try to detect stuff `<like, this>` because that's not valid HTML,
  // and we don't try to detect stuff `<like this>` because that's not valid Rust.
- if let Some(Some(generics_start)) = (is_open_tag
- && dox[..range.end].ends_with('>'))
+ let mut generics_end = range.end;
+ if let Some(Some(mut generics_start)) = (is_open_tag
+ && dox[..generics_end].ends_with('>'))
  .then(|| extract_path_backwards(&dox, range.start))
  {
+ while generics_start != 0
+ && generics_end < dox.len()
+ && dox.as_bytes()[generics_start - 1] == b'<'
+ && dox.as_bytes()[generics_end] == b'>'
+ {
+ generics_end += 1;
+ generics_start -= 1;
+ if let Some(new_start) = extract_path_backwards(&dox, generics_start) {
+ generics_start = new_start;
+ }
+ if let Some(new_end) = extract_path_forward(&dox, generics_end) {
+ generics_end = new_end;
+ }
+ }
+ if let Some(new_end) = extract_path_forward(&dox, generics_end) {
+ generics_end = new_end;
+ }
  let generics_sp = match super::source_span_for_markdown_range(
  tcx,
  &dox,
- &(generics_start..range.end),
+ &(generics_start..generics_end),
  &item.attrs,
  ) {
  Some(sp) => sp,
  None => item.attr_span(tcx),
  };
+ // Sometimes, we only extract part of a path. For example, consider this:
+ //
+ // <[u32] as IntoIter<u32>>::Item
+ // ^^^^^ unclosed HTML tag `u32`
+ //
+ // We don't have any code for parsing fully-qualified trait paths.
+ // In theory, we could add it, but doing it correctly would require
+ // parsing the entire path grammar, which is problematic because of
+ // overlap between the path grammar and Markdown.
+ //
+ // The example above shows that ambiguity. Is `[u32]` intended to be an
+ // intra-doc link to the u32 primitive, or is it intended to be a slice?
+ //
+ // If the below conditional were removed, we would suggest this, which is
+ // not what the user probably wants.
+ //
+ // <[u32] as `IntoIter<u32>`>::Item
+ //
+ // We know that the user actually wants to wrap the whole thing in a code
+ // block, but the only reason we know that is because `u32` does not, in
+ // fact, implement IntoIter. If the example looks like this:
+ //
+ // <[Vec<i32>] as IntoIter<i32>::Item
+ //
+ // The ideal fix would be significantly different.
+ if (generics_start > 0 && dox.as_bytes()[generics_start - 1] == b'<')
+ || (generics_end < dox.len() && dox.as_bytes()[generics_end] == b'>')
+ {
+ diag.emit();
+ return;
+ }
  // multipart form is chosen here because ``Vec<i32>`` would be confusing.
  diag.multipart_suggestion(
  "try marking as source code",

src/test/rustdoc-ui/suggestions/html-as-generics-no-suggestions.rs

@@ -8,6 +8,48 @@ pub struct ConstGeneric;
 // HTML tags cannot contain commas, so no error.
 pub struct MultipleGenerics;
 
+/// This <[u32] as Iterator<Item>> thing!
+//~^ERROR unclosed HTML tag `Item`
+// Some forms of fully-qualified path are simultaneously valid HTML tags
+// with attributes. They produce an error, but no suggestion, because figuring
+// out if this is valid would require parsing the entire path grammar.
+//
+// The important part is that we don't produce any *wrong* suggestions.
+// While several other examples below are added to make sure we don't
+// produce suggestions when given complex paths, this example is the actual
+// reason behind not just using the real path parser. It's ambiguous: there's
+// no way to locally reason out whether that `[u32]` is intended to be a slice
+// or an intra-doc link.
+pub struct FullyQualifiedPathsDoNotCount;
+
+/// This <Vec as IntoIter>::Iter thing!
+//~^ERROR unclosed HTML tag `Vec`
+// Some forms of fully-qualified path are simultaneously valid HTML tags
+// with attributes. They produce an error, but no suggestion, because figuring
+// out if this is valid would require parsing the entire path grammar.
+pub struct FullyQualifiedPathsDoNotCount1;
+
+/// This Vec<Vec as IntoIter>::Iter thing!
+//~^ERROR unclosed HTML tag `Vec`
+// Some forms of fully-qualified path are simultaneously valid HTML tags
+// with attributes. They produce an error, but no suggestion, because figuring
+// out if this is valid would require parsing the entire path grammar.
+pub struct FullyQualifiedPathsDoNotCount2;
+
+/// This Vec<Vec as IntoIter> thing!
+//~^ERROR unclosed HTML tag `Vec`
+// Some forms of fully-qualified path are simultaneously valid HTML tags
+// with attributes. They produce an error, but no suggestion, because figuring
+// out if this is valid would require parsing the entire path grammar.
+pub struct FullyQualifiedPathsDoNotCount3;
+
+/// This Vec<Vec<i32> as IntoIter> thing!
+//~^ERROR unclosed HTML tag `i32`
+// Some forms of fully-qualified path are simultaneously valid HTML tags
+// with attributes. They produce an error, but no suggestion, because figuring
+// out if this is valid would require parsing the entire path grammar.
+pub struct FullyQualifiedPathsDoNotCount4;
+
 /// This Vec<i32 class="test"> thing!
 //~^ERROR unclosed HTML tag `i32`
 // HTML attributes shouldn't be treated as Rust syntax, so no suggestions.

src/test/rustdoc-ui/suggestions/html-as-generics-no-suggestions.stderr

@@ -1,38 +1,68 @@
-error: unclosed HTML tag `i32`
- --> $DIR/html-as-generics-no-suggestions.rs:11:13
+error: unclosed HTML tag `Item`
+ --> $DIR/html-as-generics-no-suggestions.rs:11:28
  |
-LL | /// This Vec<i32 class="test"> thing!
- | ^^^^
+LL | /// This <[u32] as Iterator<Item>> thing!
+ |  ^^^^^^
  |
 note: the lint level is defined here
  --> $DIR/html-as-generics-no-suggestions.rs:1:9
  |
 LL | #![deny(rustdoc::invalid_html_tags)]
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+error: unclosed HTML tag `Vec`
+ --> $DIR/html-as-generics-no-suggestions.rs:25:10
+ |
+LL | /// This <Vec as IntoIter>::Iter thing!
+ | ^^^^
+
+error: unclosed HTML tag `Vec`
+ --> $DIR/html-as-generics-no-suggestions.rs:32:13
+ |
+LL | /// This Vec<Vec as IntoIter>::Iter thing!
+ | ^^^^
+
+error: unclosed HTML tag `Vec`
+ --> $DIR/html-as-generics-no-suggestions.rs:39:13
+ |
+LL | /// This Vec<Vec as IntoIter> thing!
+ | ^^^^
+
+error: unclosed HTML tag `i32`
+ --> $DIR/html-as-generics-no-suggestions.rs:46:17
+ |
+LL | /// This Vec<Vec<i32> as IntoIter> thing!
+ | ^^^^^
+
+error: unclosed HTML tag `i32`
+ --> $DIR/html-as-generics-no-suggestions.rs:53:13
+ |
+LL | /// This Vec<i32 class="test"> thing!
+ | ^^^^
+
 error: unopened HTML tag `i32`
- --> $DIR/html-as-generics-no-suggestions.rs:20:13
+ --> $DIR/html-as-generics-no-suggestions.rs:62:13
  |
 LL | /// This Vec</i32> thing!
  | ^^^^^^
 
 error: unclosed HTML tag `i32`
- --> $DIR/html-as-generics-no-suggestions.rs:25:13
+ --> $DIR/html-as-generics-no-suggestions.rs:67:13
  |
 LL | /// This 123<i32> thing!
  | ^^^^^
 
 error: unclosed HTML tag `i32`
- --> $DIR/html-as-generics-no-suggestions.rs:30:14
+ --> $DIR/html-as-generics-no-suggestions.rs:72:14
  |
 LL | /// This Vec:<i32> thing!
  | ^^^^^
 
 error: unclosed HTML tag `i32`
- --> $DIR/html-as-generics-no-suggestions.rs:35:39
+ --> $DIR/html-as-generics-no-suggestions.rs:77:39
  |
 LL | /// This [link](https://rust-lang.org)<i32> thing!
  | ^^^^^
 
-error: aborting due to 5 previous errors
+error: aborting due to 10 previous errors
 

src/test/rustdoc-ui/suggestions/html-as-generics.fixed

@@ -30,3 +30,43 @@ pub struct BareTurbofish;
 //~^ERROR unclosed HTML tag `i32`
 //~|HELP try marking as source
 pub struct Nested;
+
+/// Nested generics `Vec<Vec<u32>>`
+//~^ ERROR unclosed HTML tag `u32`
+//~|HELP try marking as source
+pub struct NestedGenerics;
+
+/// Generics with path `Vec<i32>::Iter`
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct GenericsWithPath;
+
+/// Generics with path `<Vec<i32>>::Iter`
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithPath;
+
+/// Generics with path `Vec<Vec<i32>>::Iter`
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithPath2;
+
+/// Generics with bump `<Vec<i32>>`s
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithBump;
+
+/// Generics with bump `Vec<Vec<i32>>`s
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithBump2;
+
+/// Generics with punct `<Vec<i32>>`!
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithPunct;
+
+/// Generics with punct `Vec<Vec<i32>>`!
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithPunct2;

src/test/rustdoc-ui/suggestions/html-as-generics.rs

@@ -30,3 +30,43 @@ pub struct BareTurbofish;
 //~^ERROR unclosed HTML tag `i32`
 //~|HELP try marking as source
 pub struct Nested;
+
+/// Nested generics Vec<Vec<u32>>
+//~^ ERROR unclosed HTML tag `u32`
+//~|HELP try marking as source
+pub struct NestedGenerics;
+
+/// Generics with path Vec<i32>::Iter
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct GenericsWithPath;
+
+/// Generics with path <Vec<i32>>::Iter
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithPath;
+
+/// Generics with path Vec<Vec<i32>>::Iter
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithPath2;
+
+/// Generics with bump <Vec<i32>>s
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithBump;
+
+/// Generics with bump Vec<Vec<i32>>s
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithBump2;
+
+/// Generics with punct <Vec<i32>>!
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithPunct;
+
+/// Generics with punct Vec<Vec<i32>>!
+//~^ ERROR unclosed HTML tag `i32`
+//~|HELP try marking as source
+pub struct NestedGenericsWithPunct2;