doctests fail with rust 1.26

[johanneskoester]

Input C/C++ Header

    /**
     *  bcf_hdr_set_samples() - for more efficient VCF parsing when only one/few samples are needed
     *  @samples: samples to include or exclude from file or as a comma-separated string.
     *              LIST|FILE   .. select samples in list/file
     *              ^LIST|FILE  .. exclude samples from list/file
     *              -           .. include all samples
     *              NULL        .. exclude all samples
     *  @is_file: @samples is a file (1) or a comma-separated list (0)
     *
     *  The bottleneck of VCF reading is parsing of genotype fields. If the
     *  reader knows in advance that only subset of samples is needed (possibly
     *  no samples at all), the performance of bcf_read() can be significantly
     *  improved by calling bcf_hdr_set_samples after bcf_hdr_read().
     *  The function bcf_read() will subset the VCF/BCF records automatically
     *  with the notable exception when reading records via bcf_itr_next().
     *  In this case, bcf_subset_format() must be called explicitly, because
     *  bcf_readrec() does not see the header.
     *
     *  Returns 0 on success, -1 on error or a positive integer if the list
     *  contains samples not present in the VCF header. In such a case, the
     *  return value is the index of the offending sample.
     */
    int bcf_hdr_set_samples(bcf_hdr_t *hdr, const char *samples, int is_file);

Bindgen Invocation

let bindings = bindgen::Builder::default()
        .header("wrapper.h")
        .blacklist_type("max_align_t")
        .generate()
        .expect("Unable to generate bindings.");
    bindings
        .write_to_file(out.join("bindings.rs"))
        .expect("Could not write bindings.");

Actual Results

The bindings build correctly, but when I run cargo test I get the following error when rust 1.26 tries to build run doctests:

---- target/debug/build/rust-htslib-72a070073c29be22/out/bindings.rs - htslib::bcf_hdr_set_samples (line 7071) stdout ----
	error: expected one of `!`, `.`, `::`, `;`, `?`, `{`, `}`, or an operator, found `all`
 --> target/debug/build/rust-htslib-72a070073c29be22/out/bindings.rs:7072:12
  |
3 | .. include all samples
  |            ^^^ expected one of 8 possible tokens here

error[E0423]: expected value, found macro `include`
 --> target/debug/build/rust-htslib-72a070073c29be22/out/bindings.rs:7072:4
  |
3 | .. include all samples
  |    ^^^^^^^ did you mean `include!(...)`?

error[E0308]: mismatched types
 --> target/debug/build/rust-htslib-72a070073c29be22/out/bindings.rs:7072:1
  |
2 | fn main() {
  |           - expected `()` because of default return type
3 | .. include all samples
  | ^^^^^^^^^^ expected (), found struct `std::ops::RangeTo`
  |
  = note: expected type `()`
             found type `std::ops::RangeTo<_>`

thread 'rustc' panicked at 'couldn't compile the test', librustdoc/test.rs:306:13
note: Run with `RUST_BACKTRACE=1` for a backtrace.

The generated bindings are

extern "C" {
    /// bcf_hdr_set_samples() - for more efficient VCF parsing when only one/few samples are needed
    /// @samples: samples to include or exclude from file or as a comma-separated string.
    /// LIST|FILE   .. select samples in list/file
    /// ^LIST|FILE  .. exclude samples from list/file
    /// -           .. include all samples
    /// NULL        .. exclude all samples
    /// @is_file: @samples is a file (1) or a comma-separated list (0)
    ///
    /// The bottleneck of VCF reading is parsing of genotype fields. If the
    /// reader knows in advance that only subset of samples is needed (possibly
    /// no samples at all), the performance of bcf_read() can be significantly
    /// improved by calling bcf_hdr_set_samples after bcf_hdr_read().
    /// The function bcf_read() will subset the VCF/BCF records automatically
    /// with the notable exception when reading records via bcf_itr_next().
    /// In this case, bcf_subset_format() must be called explicitly, because
    /// bcf_readrec() does not see the header.
    ///
    /// Returns 0 on success, -1 on error or a positive integer if the list
    /// contains samples not present in the VCF header. In such a case, the
    /// return value is the index of the offending sample.
    pub fn bcf_hdr_set_samples(
        hdr: *mut bcf_hdr_t,
        samples: *const ::std::os::raw::c_char,
        is_file: ::std::os::raw::c_int,
    ) -> ::std::os::raw::c_int;
}

Expected Results

I expect all doctests to pass. In particular, as I understood previous issues (e.g., #426) rust should even skip them in such a case. Is this a regression or an intended change in rust 1.26? It worked fine with rust 1.25.

[emilio]

I guess this should be an issue in the rust repo, unless it's a bindgen regression.

[emilio]

The relevant C comment from #1478 is:

https://github.com/FFmpeg/FFmpeg/blob/10506de9ad1fb050737ef79cf4853742b793c37d/libavcodec/avcodec.h#L3201

I don't think it really makes sense to run doctests on comments that come from FFI headers, but I'm not aware of any way to skip them in a per-module basis.

[Michael-F-Bryan]

I just encountered the same problem when translating this function.

It's pretty easy to see why rustdoc complains about broken tests around line 8109 of the generated code, although it doesn't look like there's an easy way for bindgen to fix the problem.

In my case an easy workaround is to blacklist the function and write its extern manually.

[jamcleod]

So @emilio I think a reasonable solution to this is to use the same detection code as a rustdoc to detect if any untagged (i.e. doesn't manually specify ```rust) codeblocks exist in the generated code, and if the code is not explicitly Rust code, tag it as no_run (or probably more likely tag it as C or C++). If that's an agreeable fix, I'm down to submit a PR. But I think assuming that C/C++ doc examples are written in Rust (the current behavior) is... weird.

Curious to know your thoughts on how to go about fixing this issue though!

[emilio]

Right, I don't see a great solution here that doesn't involve parsing the doc comments, which is kinda nasty. I think ideally adding a rustdoc attribute to ignore this would be better, but see rust-lang/rust#38825