search

rust-lang / rust-bindgen

Automatically generates Rust FFI bindings to C (and some C++) libraries.
https://rust-lang.github.io/rust-bindgen/
BSD 3-Clause "New" or "Revised" License
4.23k stars 679 forks source link

Bindgen does not keep documentation of #define constants #2756

Open HadrienG2 opened 4 months ago

HadrienG2 commented 4 months ago

C libraries commonly (ab)use defines to represent compilation constants. Therefore, the Doxygen documentation of these defines can contain valuable information and should be kept by bindgen, but alas it currently does not happen.

I am well aware that because defines are handled by the preprocessor, solving this may be harder than it sounds...

Input C/C++ Header

/** \brief Current component and plugin ABI version (see hwloc/plugins.h) */
#define HWLOC_COMPONENT_ABI 7

Bindgen Invocation

$ bindgen input.h

Actual Results

Bindgen discards the docs:

pub const HWLOC_COMPONENT_ABI: u32 = 7;

Expected Results

Bindgen keeps the docs around:

#[doc = " \brief Current component and plugin ABI version (see hwloc/plugins.h) "]
pub const HWLOC_COMPONENT_ABI: u32 = 7;
pvdrz commented 3 months ago

You are right, solving it seems to be harder than it looks.

I tried to parse the comment when the clang cursor is under a macro definition and we get null. There doesn't seem to be any way to fetch this info from the clang API: https://clang.llvm.org/doxygen/classclang_1_1MacroDefinition.html. MacroInfo doesn't have any info regarding documentation or comments.

So it seems this is not something we can do unless someone makes a custom parser for it which sounds like a lot of work.