Thanks for a good product!
In our company uses C++ we document methods along the following lines.
1) Documentation follows the method header. This removes the need for repeating the method name in the documentation. (Reducancy is bad in code).
2) Arguments are grouped into two groups, In and Out.
3) The first and the following lines of the In and the Out sections, repectively, are formatted differently.
The documentation snipplet does not allow for any of the above options.
As a solution to 1 I suggest that you introduce a macro called $SIGNATURE$. In our case, we would write the documentation snipplet like this:
$SIGNATURE$
/* ... */
If not specified, $SIGNATURE$ is assumed at the end of the snipplet, like this:
/* ... */
$SIGNATURE$
The above would be the same as writing just the following:
/* ... */
A solution to 2 is that you introduce the following new macros:
$INPUTARG$
$OUTPUTARG$
A documentation snipplet can then be written like this:
/* In: $INPUTARG$
Out: $OUTPUTARG$
*/
In C++ you can use heuristics to group arguments into input and outputs. Below are some examples:
int A -> input (pass by value)
int &B -> output (reference to modifiable data)
int const &C -> input (reference to constant data)
int const *pE -> input (pointer to constant data)
int *pD -> output (pointer to modifiable data)
A solution to 3 is that you introduce the following new macros:
$INPUTARG1$
$INPUTARGN$
$OUTPUTARG1$
$OUTPUTARGN$
A documentation snipplet can then be written like this:
$SIGNATURE$
/* In: $INPUTARG1$
$INPUTARGN$
Out: $OUTPUTARG1$
$OUTPUTARGN$
Return:
*/
Here is an example:
int SafeDivide(int A, int B, bool &Ok)
/* Purpose:
In: A -
B -
Out: Ok -
Return:
*/ {
Ok = B != 0;
return B ? A/B : 0;
} // SafeDivide
Here is the finished declaration, after some additinal manual input:
Here is an example to illustrate:
int SafeDivide(int A, int B, bool &Ok)
/* Purpose: Divde two numbers.
In: A - Numerator
B - Denumerator
Out: Ok - Able to divide?
Return: 0 if B is zero. A/B otherwise.
*/ {
Ok = B != 0;
return B ? A/B : 0;
} // SafeDivide
Best regards,
Magne
More flexible method documentation snipplet
Posted - Jun 17 2009 : 06:08:51 AM
