Generate doc comments for structs

[jsantell]

When generating headers, doc comments for structs and enums are not generated in the headers. We'd like to support Doxygen style docs e.g. with @class for structs and @memberof bindings for functions, to both annotate our structs, and organize our functions. Is this currently supported (I see that enums and structs have emit_docs() in their implementation) or any guidance/suggestions on where this can be implemented?

Example:

#[derive_ReprC]
#[ReprC::opaque]
/// This is a foo object.
/// @class foo_t
pub struct Foo {}

#[ffi_export]
/// Creates a new foo_t.
/// @memberof foo_t
pub fn new_foo() -> Option<repr_c::Box<Foo>> { .. }

generates something like:

typedef struct Foo Foo_t;

/** \brief
 *  Creates a new foo_t.
 * @memberof foo_t
 */
Foo_t* new_foo();

Thanks!

[danielhenrymantilla]

So, this is the code that handles C header generation for opaque types:

safer_ffi/src/headers/languages/c.rs

Lines 144 to 161 in bb55971

	fn emit_opaque_type (
	self: &'_ Self,
	ctx: &'_ mut dyn Definer,
	docs: Docs<'_>,
	self_ty: &'_ dyn PhantomCType,
	) -> io::Result<()>
	{
	let ref indent = Indentation::new(4 /* ctx.indent_width() */);
	mk_out!(indent, ctx.out());
	let short_name = self_ty.short_name();
	let full_ty_name = self_ty.name(self);
	self.emit_docs(ctx, docs, indent)?;
	out!(("typedef struct {short_name} {full_ty_name};"));
	out!("\n");
	Ok(())
	}

• with emit_docs doing:

  safer_ffi/src/headers/languages/c.rs

  Lines 23 to 28 in bb55971

  	out!(("/** \\brief"));
  	for line in docs.iter().copied().map(str::trim) {
  	let sep = if line.is_empty() { "" } else { " " };
  	out!((" *{sep}{line}"));
  	}
  	out!((" */"));

And for functions:

safer_ffi/src/headers/languages/c.rs

Lines 163 to 174 in bb55971

	fn emit_function (
	self: &'_ Self,
	ctx: &'_ mut dyn Definer,
	docs: Docs<'_>,
	fname: &'_ str,
	args: &'_ [FunctionArg<'_>],
	ret_ty: &'_ dyn PhantomCType,
	) -> io::Result<()>
	{
	let ref indent = Indentation::new(4 /* ctx.indent_width() */);
	self.emit_docs(ctx, docs, indent)?;

I think the difficulty here would be for @memberof to be auto-generated (@class would be quite easy to auto-generate); but if hand-annotated as with your Rust code example then it should work; if it doesn't then I might have a bug with the macro layer that calls into these helper functions.

• Note: currently non-alpha-release on crates.io is 0.0.10, which is rather old. The code I have been referring to is for 0.1.0-rc1, so hopefully that version fixes the issue?

[jsantell]

Thanks for the update! Updating our project with 0.1.0-rc1, confirming that struct comments are being generated, and bonus that #[derive_ReprC(rename = "new_name")] works as well! The @memberof and @class are to be hand-annotated anyway, the issue here was that in 0.0.10, structs did not render out associated comments in the header, which seems to be fixed in the latest RC!

Any timelines on landing non-RC 0.1.0?

Closing this issue, thank you!

[danielhenrymantilla]

Any timelines on landing non-RC 0.1.0?

It should be rather soon (~2 weeks), I just need to take the time to polish outstanding oversights I may have missed, once I find the time for that: #157