-
Notifications
You must be signed in to change notification settings - Fork 682
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Feature request: Generate Rust docs from Doxygen comments #955
Comments
@Ploppz, Can you provide some examples for whoever might pick up this issue? Thanks! |
@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;
} |
I don't see it in the docs generated by |
See https://docs.rs/nrfxlib-sys/0.1.6/nrfxlib_sys/ for an example of where Doxygen comments don't translate well.
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 |
Is the direction argument ( |
Here are some docs generated by 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 ( 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 );
|
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 .. |
Expanding a little bit to @thejpster's comments for some of the more common commands:
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 It would be very interesting to optionally use The full doxygen command list is here: https://doxygen.nl/manual/commands.html |
I wonder if we could add some sort of callback to handle comments so |
Hey @Techie-Pi is working on I'm wondering if the maintainers here would be open to adding your crate as a dependency, or if you were sort of planning to try to upstream your crate here. I like @pvdrz's idea about a docs callback in any case, that would be nicely flexible. |
@tgross35 My current plan is to create something (maybe not with the best inner workings), but functional and easy to use (see doxygen-rs-cli). If the maintainers of bindgen think this is inside the scope of the project, I'll be completely up to working on adding this as a feature of bindgen, fixing the code, moving repos or whatever is needed :) For example, this is being used on the rust-3ds/ctru-rs repo (PR with latest improvements to doxygen-rs: ref), and it seems to work almost flawlessly. There is still a lot of work, but it is for the most part feasible PS. The docs related to compatible tags are outdated, see the tracking issue for more details ;p PSS. If anyone want to use the project and has any troubles, hit me up! |
That's awesome, great to hear it's working well! I'm curious what the maintainers think (pvdrz I think you're involved here, but @emilio what are your thoughts?) The callback idea seems straightforward enough, with Techie-Pi's work as the default. Only thing is that I don't think this would allow for using doxygen comments to optionally hint mutability like I had suggested earlier - not that this is a pressing feature, but it may be a "nice to have" optional flag some day to ease abstraction design. |
My only intention with the callback API is not having to add extra dependencies to bindgen to achieve this. Maybe the callback implementation using doxygen could be in the user guide so folks now how to use it if required but I'd prefer not having |
Yeah, me neither, I think the callback API is the best option here tbh. But if I can help with any Doxygen-related thing or something, I'm up to helping! |
#2347 would allow users to handle comments however they want. For example: impl ParseCallbacks for Cb {
fn process_comment(&self, comment: &str, _indentation_level: usize) -> Option<String> {
Some(
comment
.lines()
.fold("/// ````c,ignore".to_owned(), |acc, x| acc + "\n/// "+ x)
+ "\n/// ````",
)
}
} can be used to escape all comments inside markdown code blocks. I suppose that after removing the comment delimiters, |
Agreed that callback seems like the way to go. Some sort of builtin that does the basics (like remove the annoying Tangential question, is there any reason that bindgen uses the |
There are some ongoing discussions about this. If it were my decision I'd just escape everything using quadruple backticks but there might be some issues with that.
The main reason is that fn main() {
let comment = "hello world!";
// This is **not** `/// hello world!`
let x = quote::quote! {
/// #comment
};
println!("{}", x); // Will print `# [doc = r" #comment"]`
} |
Sorry, what would the triple backticks be for? I see them mentioned here in the context of markdown, but I didn't see the connection to Thanks for the clarification on |
Putting all the docstring between quadruple backticks would allow you to show them as a code block in markdown syntax with few chances of having escaping issues. |
now that #2347 landed you can provide an implementation of |
Right now I'm not able to implement this, but in the following weeks I'll add support for this to doxygen-rs |
@Techie-Pi from the #[derive(Debug)]
struct Cb;
impl ParseCallbacks for Cb {
fn process_comment(&self, comment: &str) -> Option<String> {
Some(doxygen_rs::transform(comment))
}
} |
I think it would be very useful to be able to tell bindgen to parse Doxygen comments and generate Rust doc comments.
The text was updated successfully, but these errors were encountered: