Strip leading \brief or \short at the start of Doxygen comment

[HadrienG2]

rustdoc treats the first paragraph of an item's description as a brief description to be used in higher level docs (module item list, etc). Historically, Doxygen has required use of \brief or \short to achieve the same effect. Nowadays you can use JAVADOC_AUTOBRIEF instead, but many older C/++ projects will still use the \brief or \short Doxygen directive style.

As a result, the autogenerated rustdoc ends up being spammed with leading \briefs:

It would be great if bindgen could detect \briefs at the start of Doxygen comments and strip them off instead.

Input C/C++ Header

/** \brief Object info attribute (name and value strings)
 *
 * \sa hwlocality_info_attr
 */
struct hwloc_info_s {};

Bindgen Invocation

$ bindgen input.h

Actual Results

Bindgen keeps the leading \brief in the rustdoc output, resulting in the rustdoc \brief spam illustrated above.

#[doc = " \\brief Object info attribute (name and value strings)\n\n \\sa hwlocality_info_attr"]
#[repr(C)]
#[derive(Debug, Copy, Clone)]
pub struct hwloc_info_s {}

Expected Results

Bindgen strips the leading \brief to switch to rustdoc's brief description convention.

#[doc = "Object info attribute (name and value strings)\n\n \\sa hwlocality_info_attr"]
#[repr(C)]
#[derive(Debug, Copy, Clone)]
pub struct hwloc_info_s {}

[laurooyen]

I've come across a similar problem with same-line documentation, often used for struct fields or enums.

enum Foo {
    FOO_A, ///< A description
    FOO_B, ///< Another description
};

The < is copied over to the Rust documentation. A generic solution to trim the start of documentation strings, maybe through ParseCallbacks could be usefull.

[pvdrz]

Sounds like something you could do via process_comment, see: https://crates.io/crates/doxygen-rs/0.4.2

[pvdrz]

I'm closing this issue as doxygen-rs should be able to handle both your use cases. I think any extra functionality regarding doxygen parsing should be requested to the doxygen-rs' folks to avoid duplication of efforts and because they probably have a better idea of how to solve such issues than us.