Feature request: documentation macro for functions

[SeseMueller]

Using the crate, I was surprised that it only supports documenting of types.

I understand that the current code does not directly support it as it uses a derive macro, but I think the ability to extract the docstring from other parts of a codebase, especially functions, might be very useful in specific circumstances.

The idea is that it would be possible to simply annotate a function with a macro, similar to how types are currently anotated using the crate:

/// Helpful docs
#[document_function]
pub fn my_function(){}

// == becomes =>

/// Helpful docs
pub fn my_function(){}
const my_function_docs: &str = "Helpful docs";

Of course, since functions do not support the my_function::DOCS syntax, the docstring would need to be written to a const variable. Unfortunately, this is far more intrusive to the codebase than the derive macro. The variable to contain the docstring should probably be called my_function_docs or something similar.

I'm not very deep into macro magic, but from what I read, the docs are also just an attribute that should be directly readable from a proc macro.

I came up with this feature request while writing a REST API. The feature would allow one to easily keep documentation for the endpoint to stay in sync between the codebase and potential outside documentation with much more control than other crates that do so using manual writing of the documentation.

[cyqsimon]

I completely understand and agree with you that this is a valuable need. In fact, it was during writing my project using Actix that I ran across this need in the first place, which I'm guessing is pretty much identical to your use case.

As you have conjectured, the reason I have not implemented such a macro for functions is entirely technical. Unlike you can with types, there is currently no way to "attach" constants/properties/methods to functions. By extension, it's also not possible to put a derive macro on functions because there is nothing to be derived.

Of course, since functions do not support the my_function::DOCS syntax, the docstring would need to be written to a const variable. Unfortunately, this is far more intrusive to the codebase than the derive macro. The variable to contain the docstring should probably be called my_function_docs or something similar.

This is the only other alternative I see as well in lieu of the aforementioned feature. This would be an attribute macro, and the generated code would no doubt be cumbersome. But as long as we allow the user to customise the name of the generated constant, I think it is a reasonable compromise.

And finally, are you interested in working on a PR? Please let me know, thanks!

[SeseMueller]

Thanks for the quick response! Yes, I am interested in working on it, but I currently have little time. I would do it within a few weeks.

[cyqsimon]

Closed by #13.