Feature request: Generate Rust docs from Doxygen comments

[Ploppz]

I think it would be very useful to be able to tell bindgen to parse Doxygen comments and generate Rust doc comments.

[fitzgen]

@Ploppz, Can you provide some examples for whoever might pick up this issue? Thanks!

[Ploppz]

I'm currently working with this C++ library. Examples: the functions here. At least I think that's Doxygen... The structs don't have doxygen comments though, but I think that should be possible too.

[fitzgen]

@Ploppz we do generate rust doc comments (they aren't necessarily pretty) and I'm not sure what concrete changes you're asking for in this issue. For example:

/**
 * Does the stuff.
 *
 * @returns whatever
 */
bool demboogy(int x, int y);

becomes

/* automatically generated by rust-bindgen */

extern "C" {

    /// Does the stuff.
    ///
    /// @returns whatever

    #[link_name = "_Z8demboogyii"]
    pub fn demboogy(x: ::std::os::raw::c_int, y: ::std::os::raw::c_int)
        -> bool;
}

[Ploppz]

I don't see it in the docs generated by cargo doc --open. I uploaded the code here. Neither the functions nor the structs have documentation comments, it seems.

[thejpster]

See https://docs.rs/nrfxlib-sys/0.1.6/nrfxlib_sys/ for an example of where Doxygen comments don't translate well.

• @brief should be removed.
• @defgroup <group_name> <label> should be used to create groups, or removed.
• @ingroup <group_name> should be used to put items into groups, or removed.
• @param <param_name> <label> should be used to label a function parameter.

As a first pass, it would be helpful to retain the newlines from the original comments, so that these items were each on a line on their own, rather than all thrown into a single line. Actually, I might try doing a post-bindgen regexp in my build.rs as a workaround and see if that helps.

[NickeZ]

Is the direction argument (in/out) like @param[in] supposed to work? It doesn't seem to work for me.

[virtualritz]

Here are some docs generated by bindgen (more or less trying to mirror Sphinx formatting here):

---

AcquireSuite: Option<unsafe extern "C" fn(name: *const c_char, version: c_int, suite: *mut *const c_void) -> SPErr>

Acquires a function suite. Loads the suite if necessary, and increments its reference count. For example: @code SPErr error; SPBasicSuite *sBasic = message->d.basic; AIRandomSuite *sRandom; sBasic->AcquireSuite( kAIRandomSuite, kAIRandomVersion, &sRandom ); @Endcode @param name The suite name. @param version The suite version number. @param suite [out] A buffer in which to return the suite pointer. @see \c #SPSuitesSuite::AcquireSuite()

---

As you can see Doxygen hints (@whatever) and newlines are just ignored.
As @thejpster said: keeping newlines would already help, as a 1st step.
If Doxygen hints were supported too it would look more like this:

---

AcquireSuite: Option<unsafe extern "C" fn(name: *const c_char, version: c_int, suite: *mut *const c_void) -> SPErr>

Acquires a function suite. Loads the suite if necessary, and increments its reference count. For example:

SPErr error;
SPBasicSuite *sBasic = message->d.basic;
AIRandomSuite *sRandom;
sBasic->AcquireSuite( kAIRandomSuite, kAIRandomVersion, &sRandom ); 

name – The suite name.
version – The suite version number.
suite [out] – A buffer in which to return the suite pointer.
See also: SPSuitesSuite::AcquireSuite()

---

[necrose99]

a rs-doxygen would be a plus , ie not use it but be a drop in , when it breaks , pkgs building brreak.

if doxygen breaks , can run .. a compat cli tool. cargo-doxygen anyone ..

[tgross35]

Expanding a little bit to @thejpster's comments for some of the more common commands:

• @briefrepresents a one line summary, so it can be removed. Or, make this the first line in the documentation block (it probably will be the first line anyway). It would be good to insert a line break before any further @xxx attributes, to make sure this goes on its own line
• @copydoc MyClass::myfunction() Copies the documentation from another module, could do the same here
• \@ escaped at symbol, can just remove the slash
• @sa { references } Used to link to other sections. This could somehow influence paths for [attr]
• @todo Maybe just change to TODO:?
• @param is used for each argument, and includes an optional [in], [out], or [in,out]. Example:

 * @param[out] dest The memory area to copy to.
 * @param[in]  src  The memory area to copy from.
 * @param[in]  n    The number of bytes to copy
void memcpy(void *dest, const void *src, size_t n);

The unofficial canonical way to describe arguments is:

/// Arguments:
///
/// * `dest`: The memory area to copy to.
/// * `src`: The memory area to copy from.
/// * `n`: The number of bytes to copy

Which should be easy enough to generate. There is talk under rustdoc to support something for per-argument /// attributes - but this doesn't seem to have gotten far, so likely not worth worrying about for now.

It would be very interesting to optionally use [in]/[in,out] or [out] to determine the mutability of arguments, which would be more clear than including the information in documentation.

The full doxygen command list is here: https://doxygen.nl/manual/commands.html