rust-bindgen bindgen fails to generate comments (at all)

Input C/C++ Header

I was unable to correctly minimize a header, however here are the dumped pre-processed inputs:

https://gist.github.com/lovesegfault/bc38d2d09c679c6df0b3d63468bf8735

Bindgen Invocation

    bindgen::Builder::default()
        .header_contents("wrapper.h", "#include<chromaprint.h>")
        .generate_comments(true)
        .layout_tests(true)
        .parse_callbacks(Box::new(bindgen::CargoCallbacks))
        .rustfmt_bindings(true)
        .generate()
        .expect("Failed to generate chromaprint bindings")
        .write_to_file(out_path.join("bindings.rs"))
        .expect("Failed to write bindings");

Actual Results

extern "C" {
    pub fn chromaprint_new(algorithm: ::std::os::raw::c_int) -> *mut ChromaprintContext;
}

Expected Results

Something like this:

extern "C" {
    /// Allocate and initialize the Chromaprint context.
    ///
    /// Note that when Chromaprint is compiled with FFTW, this function is
    /// not reentrant and you need to call it only from one thread at a time.
    /// This is not a problem when using FFmpeg or vDSP.
    ///
    /// @param algorithm the fingerprint algorithm version you want to use, or
    ///		CHROMAPRINT_ALGORITHM_DEFAULT for the default algorithm
    ///
    /// @return ctx Chromaprint context pointer
    pub fn chromaprint_new(algorithm: ::std::os::raw::c_int) -> *mut ChromaprintContext;
}

This issue happens for the entire API of chromaprint, and can be easily reproduced like so:

git clone https://github.com/lovesegfault/chromaprint_sys
cd chromaprint_sys
nix-shell
cargo build
vim ./target/debug/build/chromaprint_sys-*/out/bindings.rs

Mar 17 '20 01:03 lovesegfault

This one is interesting, thanks for the report!

Mar 21 '20 18:03 emilio

I've reproduced this one with interesting results, the bug only appears when the wrapper header is not using absolute paths.

$ cat wrapper_tmp.h
#include <SDL2/SDL.h>

$ bindgen --no-recursive-allowlist --allowlist-function SDL_IsTablet ./wrapper_tmp.h
/* automatically generated by rust-bindgen 0.61.0 */

extern "C" {
        pub fn SDL_IsTablet() -> SDL_bool;
}

$ cat wrapper_tmp2.h
#include </usr/include/SDL2/SDL.h>

$ bindgen --no-recursive-allowlist --allowlist-function SDL_IsTablet ./wrapper_tmp2.h
/* automatically generated by rust-bindgen 0.61.0 */

extern "C" {
        #[doc = " Query if the current device is a tablet."]
        #[doc = ""]
        #[doc = " If SDL can't determine this, it will return SDL_FALSE."]
        #[doc = ""]
        #[doc = " \\returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise."]
        #[doc = ""]
        #[doc = " \\since This function is available since SDL 2.0.9."]
        pub fn SDL_IsTablet() -> SDL_bool;
}

This example used SDL2 but this is reproducible on other system headers with doc comments, such as wayland-client.

Edit: The same thing appears on version 0.63.0, though now the doc comment is all on one line

$ cat wrapper_tmp.h
#include <SDL2/SDL.h>

$ bindgen --no-recursive-allowlist --allowlist-function SDL_IsTablet ./wrapper_tmp.h
/* automatically generated by rust-bindgen 0.63.0 */

extern "C" {
        pub fn SDL_IsTablet() -> SDL_bool;
}

$ cat wrapper_tmp2.h
#include </usr/include/SDL2/SDL.h>

$ bindgen --no-recursive-allowlist --allowlist-function SDL_IsTablet ./wrapper_tmp2.h
/* automatically generated by rust-bindgen 0.63.0 */

extern "C" {
        #[doc = " Query if the current device is a tablet.\n\n If SDL can't determine this, it will return SDL_FALSE.\n\n \\returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise.\n\n \\since This function is available since SDL 2.0.9."]
        pub fn SDL_IsTablet() -> SDL_bool;
}

Edit 2: Note that this is entirely unaffected by the other arguments, --no-recursive-allowlist --allowlist-function, those were just to get a minimal example. Running without them and scrolling down to the same function, we still get the same output:

$ bindgen ./wrapper_tmp.h | less
...
extern "C" {
        pub fn SDL_IsTablet() -> SDL_bool;
}
...

$ bindgen ./wrapper_tmp2.h | less
...
extern "C" {
        #[doc = " Query if the current device is a tablet.\n\n If SDL can't determine this, it will return SDL
_FALSE.\n\n \\returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise.\n\n \\since This function is av
ailable since SDL 2.0.9."]
        pub fn SDL_IsTablet() -> SDL_bool;
}
...