Blank line in comment block causes error

[the-other-james]

Input C/C++ Header

/*****************************************************************************/
/**
** \brief Simple function to demonstrate possible bindgen bug
**
** \par Description
**        This is the first paragraph. It is fine. There seems to be no issues
**        with multiple lines.
**
**        This second paragraph after the blank ("**") line causes problems.
**
** \par Another section
**        It seems to be fine to have a new section. No problems here.
**
** \param[in]  a   The first dummy arg
**
** \param[in]  b   The second dummy arg
**
** \returns
**      0  If I feel like it
**      1  otherwise
**      83 Just for kicks every now and then
**
******************************************************************************/
int simple_function(int a, int b);

/*****************************************************************************/
/**
** \brief A second simple function to help demonstrate a possible bindgen bug
**
** \par Description
**        This is the first paragraph. It is fine. There seems to be no issues
**        with multiple lines.
**A
**        Adding a single (non-whitespace) character to the previous line fixes
**        the issue.
**
** \par Another section
**        It seems to be fine to have a new section. No problems here.
**
** \param[in]  a   The first dummy arg
**
** \param[in]  b   The second dummy arg
**
** \returns
**      0  If I feel like it
**      1  otherwise
**      83 Just for kicks every now and then
**
******************************************************************************/
int simple_function2(int a, int b);

Bindgen Invocation

bindgen::Builder::default()
        .header("wrapper.h")
        .parse_callbacks(Box::new(bindgen::CargoCallbacks))
        .generate()
        .expect("Unable to generate bindings");

Actual Results

$ RUST_BACKTRACE=1 cargo test
    Finished test [unoptimized + debuginfo] target(s) in 0.04s
     Running target/debug/deps/doc_example-c5b6e6a8071d3dd7

running 1 test
test tests::it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

   Doc-tests doc_example

running 1 test
test target/debug/build/doc_example-e79f5c3b13701f4b/out/bindings.rs - simple_function (line 10) ... FAILED

failures:

---- target/debug/build/doc_example-e79f5c3b13701f4b/out/bindings.rs - simple_function (line 10) stdout ----
error: expected one of `!`, `.`, `::`, `;`, `?`, `{`, `}`, or an operator, found `second`
 --> target/debug/build/doc_example-e79f5c3b13701f4b/out/bindings.rs:11:6
  |
3 | This second paragraph after the blank ("**") line causes problems.
  |      ^^^^^^ expected one of 8 possible tokens

error: aborting due to previous error

Couldn't compile the test.

failures:
    target/debug/build/doc_example-e79f5c3b13701f4b/out/bindings.rs - simple_function (line 10)

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out

error: test failed, to rerun pass '--doc'

Expected Results

I would expect cargo test to work, and indeed it does if the blank ("**") line before the second paragraph in the description has a character added to it (see the comment block for simple_function2; it works fine).

I'm brand new to bindgen, so please let me know if you need more info / I've omitted anything. Thanks!

[emilio]

This is a known issue, where we copy the doc comments from C, but cargo interprets markdown as rust code and thus it fails.

You can disable doc tests when running cargo, or disable comment generation. See also #426 / #800.

Closing as a dupe of the later one... Ideally we should be able to somehow tell cargo to ignore them.