Missing docstrings depending on include path

[lnicola]

Sorry for not having a minimal example, but this should show the issue. I'm running it on Arch Linux with the gdal package installed.

Is there anything I should be aware of when choosing the bindgen input and include paths?

$ rm -rf include; cp /usr/include include; cat wrapper2.h
#include <ogr_srs_api.h>

$ bindgen wrapper2.h -- -I /usr/include | rg -B1 OSRSetSCH
extern "C" {
    pub fn OSRSetSCH(

$ bindgen wrapper2.h -- -I include | rg -B1 OSRSetSCH    
    /// Spherical, Cross-track, Height
    pub fn OSRSetSCH(

$ bindgen /usr/include/ogr_srs_api.h -- -I /usr/include | rg -B1 OSRSetSCH 
    /// Spherical, Cross-track, Height
    pub fn OSRSetSCH(

[strohel]

I can confirm similarly weird behavior with bindgen 0.53.2:

strohel@mat480s ~/projekty/isds-rs/isds-sys $ cat wrapper.h 
#include <isds.h>
strohel@mat480s ~/projekty/isds-rs/isds-sys $ bindgen wrapper.h -- -I /usr/include/libxml2 | grep '#\[doc' | wc -l
0
strohel@mat480s ~/projekty/isds-rs/isds-sys $ bindgen /usr/include/isds.h -- -I /usr/include/libxml2 | grep '#\[doc' | wc -l
689

I.e. it generates documentation only if /usr/include/isds.h is directly mentioned on the command line. If it is included through wrapper.h, it generates no documentation.

It is interesting that documentation for libXml types is generated in the second case, even if it comes from /usr/include/libxml2/libxml/tree.h, which is itself included from /usr/include/isds.h using #include <libxml/tree.h>.

It seems that bindgen skips docstrings of transitive header files (not directly specified) that are directly in the default include path /usr/include. (that's the only "rule" I can think of the explains all observations here)

[strohel]

Okay, I've drilled it down to clang. Thanks to these slides https://llvm.org/devmtg/2012-11/Gribenko_CommentParsing.pdf - namely slide 32:

Comments from system headers are skipped during normalcompilation.
•There is no sense in parsing them for diagnostics.
•Pass -fretain-comments-from-system-headers if youwant them back.

And indeed, passing that causes much more (too much?) comments to be extracted:

strohel@mat480s ~/projekty/isds-rs/isds-sys $ bindgen wrapper.h -- -I /usr/include/libxml2 -fretain-comments-from-system-headers | grep '#\[doc' | wc -l
2614

[strohel]

Another note (to myself, mostly): there is also -fparse-all-comments clang option that causes all comments (not just docstrings) to be parsed. And following test in clang nicely demonstrates parsing: https://github.com/llvm-mirror/clang/blob/master/test/Index/parse-all-comments.c

[emilio]

Awesome find! It'd be good to document these, I've seen a couple people ask for the ability to generate non-doxygen comments.

[strohel]

Cool, expect a docs PR from me in a couple of days.