Comment #0 by bearophile_hugs — 2012-11-15T15:32:43Z
The slides of the "Parsing Documentation Comments in Clang" talk by Dmitri Gribenko:
http://llvm.org/devmtg/2012-11/Gribenko_CommentParsing.pdf
With this feature added to Clang (you need the -Wdocumentation switch to activate it. For performance it parses comments only in this case), some C++ code with documentation comments like this:
/// \brief Does something with \p str.
/// \param [in] Str the string.
/// \returns a modified string.
void do_something(const std::string &str);
generates "notes" or warnings like this, that help keep such comments more aligned to the code:
example.cc:4:17: warning: parameter ’Str’ not found
in the function declaration [-Wdocumentation]
/// \param [in] Str the string.
^~~
example.cc:5:6: warning: ’\returns’ command used
in a comment that is attached to a function
returning void [-Wdocumentation]
/// \returns a modified string.
~^~~~~~~~~~~~~~~~~~~~~~~~~~
Or like this:
/// \param x value of X coordinate.
/// \param x value of Y coordinate.
void do_something(int x, int y);
example.cc:2:12: warning: parameter ’x’ is already
documented [-Wdocumentation]
/// \param x value of Y coordinate.
^
In D documentation comments are built-in, they are managed by the compiler and they are part of the language. I suggest to add few of such documentation tests to the D front-end, that generate warnings when the -w/-wi switches are used. I think this is not hard to implement, and it helps write more correct documentation comments.
This program contains a wrong documentation comment meant to generate some of such documentation warnings:
/**
* Params:
* x = is for this
* and not for that
* x = is for this
* and not for that
* y = is for that
*
* Returns: The contents of the file.
*/
void foo(int x, int z) {}
void main() {}
The possible warnings generated by the D compiler:
test.d(5): Warning: parameter 'x' is already documented.
test.d(7): Warning: documentation parameter 'y' not found in the function declaration.
test.d(9): Warning: 'return' value documented for function returning void.
Or:
test.d(5): Documentation Warning: parameter 'x' is already documented.
test.d(7): Documentation Warning: documentation parameter 'y' not found in the function declaration.
test.d(9): Documentation Warning: 'return' value documented for function returning void.
Or:
test.d(5): Note: parameter 'x' is already documented.
test.d(7): Note: documentation parameter 'y' not found in the function declaration.
test.d(9): Note: 'return' value documented for function returning void.
See also the forum thread:
http://forum.dlang.org/thread/[email protected]
Comment #1 by robert.schadek — 2024-12-13T18:02:55Z