In rust I use macros to implement the same code for many types. I would like to document all the implementations in one place and have one example for them. What is the proper way to do this ?
Currently I put the documentation above the macro. (It is good to keep documentation source close to its implementation). But this is really the place for documenting how to use a macro instead of how to use the code it generates.
In addition, in the documentation generated by the macro, I would like to include links to the corresponding documentation (which lives above the macro). If the macro is private (while the function generated by the macro is pubic) the links fail. So I end up making macros public that I do not want to be public.
exactly, the documentation on the macro should be for how to use the macro itself. however, depending on the situation, it can also explain how the generated code works, so in some cases, I think it could be reasonable to link the generated documentation back to the macro itself, something like "this function (or struct, or item, etc) is generated using the foobar macro, see foobar for detailed explanation"
another approach is you can put detailed documentation at the module level, and the documentation of the macro generated code then simply contains a short summary with a link to "the module-level documentation".
this documentation structure is used by many crates and the standard library, for example, the documentation for std::any::Any reads:
A trait to emulate dynamic typing.
Most types implement Any. However, any type which contains a non-'static reference does not. See the module-level documentation for more details.
1 Like
I using the following solution In order to keep the documentation close to the corresponding code. It is not great because my macro use documentation gets put under the functions heading. This is only appropriate when the documentation for the different cases is very similar; e.g., one example serves for all the cases.,
First: Documentation for how to use the code that the macro generates
Second: A dummy function of the form pub doc_for_this_macro() { }
Third: Documentation for how to use the macro
Fourth macro_rules! ...
Inside then macro rules I link back to the how to the first documentation with [doc_for_this_macro]