C javadoc comments are not Markdown-escaped, triggering `rustdoc` warnings

[ojeda]

This comes up in Rust for Linux when generating the bindings for some C APIs that happen to have javadoc-like comments that end up being broken Markdown: Rust-for-Linux/linux#323.

Input C/C++ Header

/**
 * vdso_data.cs[x].shift
 */
void f(void);

Bindgen Invocation

$ bindgen f.h

Actual Results

extern "C" {
    #[doc = " vdso_data.cs[x].shift"]
    pub fn f();
}

Which leads to rustdoc warnings such as:

warning: unresolved link to `x`
 --> f.rs:4:5
  |
4 |     #[doc = " vdso_data.cs[x].shift"]
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
  = note: the link appears in this line:
          
          vdso_data.cs[x].shift
                       ^
  = note: no item named `x` in scope
  = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

Expected Results

extern "C" {
    #[doc = " vdso_data.cs\\[x\\].shift"]
    pub fn f();
}

[emilio]

This is #1313 basically... I suspect the best path forward here is probably making sure we treat all doc comments as literal blocks of code (basically prepending triple-quotes or something) so that we don't mess up whitespace and other things people do on doc comments. There's some other discussion about this somewhere else, IIRC.

[pvdrz]

#2347 could provide a solution for this.

[zopsicle]

making sure we treat all doc comments as literal blocks of code

It would be nice to still offer the original behavior, in case a library is bindgenned which uses Markdown comments.

[pvdrz]

now that #2347 landed. This can be solved by implementing ParseCallbacks::process_comments to either wrap the comment in backticks:

#[derive(Debug)]
struct Cb;

impl ParseCallbacks for Cb {
    fn process_comment(&self, comment: &str) -> Option<String> {
        Some(format!("````\n{}\n````", comment))
    }
}

or parsing it with a javadoc parser (not sure if such thing exists in Rust)