function parameter annotation causes an issue in the relevant @param field of the "function documentation live template"
If you use function parameter annotation (_In_ for example) -- the function documentation, generated by the "function documentation live template", produces a warning and doesn't "bind" the parameter name with the @param documentation record.
The "function documentation live template" is very useful and it could be great if a functionality that would handle parameter annotations (or either ignore the annotation; it's still better than the current situation) would be added.
Please sign in to leave a comment.
Hello Eli,
Which R++ version are you using? Could you show us the code where this problem occurs? I tried to generate documentation for the following function with R++ 2016.3, and didn't get any warnings:
#include <sal.h>
void foo(_In_ int *pInt);
Thanks!
Hi Igor,
What I mean is that I'd like to add the parameter annotation to the function documentation comment.
By issuing the "function documentation live template", the parameter annotation are simply ignored for each @param. And if added manually, a "unsupported doxygen comment" warning is produced and the "binding" between the @param and the actual function parameter is nonexistent.
For example, for the function you've presented, the generated documentation will be something like -
/**
...
* @param pint
...
*/
What I'd like it to be is -
/**
...
* @param _In_ pint
...
*/
BTW, I'm using ReSharper 2016.3.1.
Please correct me if I'm wrong, but according to https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdparam this is not correct Doxygen syntax, is it not? On the other hand, we probably could add some logic specifically for SAL and deduce Doxygen's [in], [out] and [in,out] from SAL's _In_, _Out_, _Inout_ and the like.
Yes, you're correct.
If you'd add the square brackets, when generating a function's documentation comment by the live template, to match the Doxygen standards, it'd be an excellent solution. The issue is that currently, the parameter annotations are ignored, and just copying the plain syntax from the function declaration is unsupported.
So, basically, my point is -
It'd be very convenient if you could add the Doxygen standard square brackets to the generated comments by default and/or add an option to ignore the warning that's being produced when just copying the parameter annotation, alongside the parameter itself, from the function declaration into the comment (and allow the convenient "binding" of the @param with the actual parameter).
BTW, a minor issue:
I've just noticed that the live template doesn't check whether a closing square bracket is provided - adding just an opening bracket makes the comment successfully "bind" and produces no warnings.
Well, you can't just copy these annotations, since if you do that, documentation produced by doxygen will be rendered incorrectly. We also can't add square brackets automatically in most cases because R++ does not know how the param gets used. We can add ad-hoc integration specifically for SAL annotations, please vote for https://youtrack.jetbrains.com/issue/RSCPP-19171 to receive an update when this gets implemented.
Thanks for the suggestion!