Support markdown in C++ doc comments.

[emilio]

Followup from #426, and #791.

Right now if you are generating bindings to a C/C++ library that happens to use markdown blocks in its comments, will make rustdoc complain (because the comment probably isn't valid rust).

Right now the workaround is avoiding generating comments, but that's not ideal.

Testcase:

/**
 * Example usage:
 *
 * ```
 * struct Foo* my_foo = make_foo();
 * foo->random_member++;
 * ```
 */
struct Foo {
  int random_member;
};

---

Options I can think off-hand:

• Make the generated comments non-doc comments.
• Try to preprocess comments in the same way rustdoc does (presumably just looking at three backticks at the beginning of the line?) and annotate them (for markdown at least this would work).

Any other ideas @jethrogb?

[jethrogb]

I just don't think we should default to doc comments. For me, the only reason to use doc comments would be if rustdoc could do something sane with them. More often than not, that's not going to be the case with comments imported from C. From your comment in the other thread:

This PR also fixes the most common cases where people doesn't use markdown for their C/C++ docs.

Instead, sending the comments through rustdoc will either error or provide terrible-looking output. Why not just use regular comments?

In the future we can have code that detects doxygen or other common documentation styles and convert them to rust-compatible markdown.

Maybe there's a way to tell rustdoc "don't format this entire comment, escape it and include it as HTML text verbatim". That would also be ok I think.

[fitzgen]

I agree that the most practical thing to do is generate regular, non-doc comments.

[willglynn]

This just broke for me.

bindgen copies C comments into a Rust doc comments. One of the C comments has an indented section, which is another way to write a code block in Markdown. This causes cargo test to fail, because the indented text in the C source file comment isn't a valid test case for the generated Rust bindings.

[pvdrz]

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

```c++ 

by

```c++,ignore