Auto merge of rust-lang#11956 - intgr:doc_markdown-include-function-parenthesis, r=Alexendoo

[`doc_markdown`] Recognize words followed by empty parentheses `()` for quoting

*Please write a short comment explaining your change (or "none" for internal only changes)*

changelog: [`doc_markdown`] Recognize words followed by empty parentheses for quoting, e.g. `func()`.

---

Developers often write function/method names with trailing `()`, but `doc_markdown` lint did not consider that.

Old clippy suggestion was not very good:

```patch
-/// There is no try (do() or do_not()).
+/// There is no try (do() or `do_not`()).
```

New behavior recognizes function names such as `do()` even they contain no `_`/`::`; and backticks are suggested outside of the `()`:

```patch
-/// There is no try (do() or do_not()).
+/// There is no try (`do()` or `do_not()`).
```

Author: bors

clippy_lints/src/doc/markdown.rs

@@ -9,11 +9,21 @@ use url::Url;
 use crate::doc::DOC_MARKDOWN;
 
 pub fn check(cx: &LateContext<'_>, valid_idents: &FxHashSet<String>, text: &str, span: Span) {
-    for word in text.split(|c: char| c.is_whitespace() || c == '\'') {
+    for orig_word in text.split(|c: char| c.is_whitespace() || c == '\'') {
         // Trim punctuation as in `some comment (see foo::bar).`
         //                                                   ^^
         // Or even as in `_foo bar_` which is emphasized. Also preserve `::` as a prefix/suffix.
-        let mut word = word.trim_matches(|c: char| !c.is_alphanumeric() && c != ':');
+        let trim_pattern = |c: char| !c.is_alphanumeric() && c != ':';
+        let mut word = orig_word.trim_end_matches(trim_pattern);
+
+        // If word is immediately followed by `()`, claw it back.
+        if let Some(tmp_word) = orig_word.get(..word.len() + 2)
+            && tmp_word.ends_with("()")
+        {
+            word = tmp_word;
+        }
+
+        word = word.trim_start_matches(trim_pattern);
 
         // Remove leading or trailing single `:` which may be part of a sentence.
         if word.starts_with(':') && !word.starts_with("::") {
@@ -84,7 +94,7 @@ fn check_word(cx: &LateContext<'_>, word: &str, span: Span) {
         return;
     }
 
-    if has_underscore(word) || word.contains("::") || is_camel_case(word) {
+    if has_underscore(word) || word.contains("::") || is_camel_case(word) || word.ends_with("()") {
         let mut applicability = Applicability::MachineApplicable;
 
         span_lint_and_then(

clippy_lints/src/missing_asserts_for_indexing.rs

@@ -94,7 +94,7 @@ enum LengthComparison {
 
 /// Extracts parts out of a length comparison expression.
 ///
-/// E.g. for `v.len() > 5` this returns `Some((LengthComparison::IntLessThanLength, 5, `v.len()`))`
+/// E.g. for `v.len() > 5` this returns `Some((LengthComparison::IntLessThanLength, 5, v.len()))`
 fn len_comparison<'hir>(
     bin_op: BinOp,
     left: &'hir Expr<'hir>,

tests/ui/doc/doc-fixable.fixed

@@ -227,3 +227,6 @@ where [(); N.checked_next_power_of_two().unwrap()]: {
 
 /// this checks if the lowerCamelCase issue is fixed
 fn issue_11568() {}
+
+/// There is no try (`do()` or `do_not()`).
+fn parenthesized_word() {}

tests/ui/doc/doc-fixable.rs

@@ -227,3 +227,6 @@ where [(); N.checked_next_power_of_two().unwrap()]: {
 
 /// this checks if the lowerCamelCase issue is fixed
 fn issue_11568() {}
+
+/// There is no try (do() or do_not()).
+fn parenthesized_word() {}

tests/ui/doc/doc-fixable.stderr

@@ -319,5 +319,27 @@ help: try
 LL | /// Foo \[bar\] \[baz\] \[qux\]. `DocMarkdownLint`
    |                                  ~~~~~~~~~~~~~~~~~
 
-error: aborting due to 29 previous errors
+error: item in documentation is missing backticks
+  --> $DIR/doc-fixable.rs:231:22
+   |
+LL | /// There is no try (do() or do_not()).
+   |                      ^^^^
+   |
+help: try
+   |
+LL | /// There is no try (`do()` or do_not()).
+   |                      ~~~~~~
+
+error: item in documentation is missing backticks
+  --> $DIR/doc-fixable.rs:231:30
+   |
+LL | /// There is no try (do() or do_not()).
+   |                              ^^^^^^^^
+   |
+help: try
+   |
+LL | /// There is no try (do() or `do_not()`).
+   |                              ~~~~~~~~~~
+
+error: aborting due to 31 previous errors