[Issue 9032] New: Verify some documentation comments when -w or -wi is used
d-bugmail at puremagic.com
d-bugmail at puremagic.com
Thu Nov 15 15:32:49 PST 2012
http://d.puremagic.com/issues/show_bug.cgi?id=9032
Summary: Verify some documentation comments when -w or -wi is
used
Product: D
Version: D2
Platform: All
OS/Version: All
Status: NEW
Keywords: diagnostic
Severity: enhancement
Priority: P2
Component: DMD
AssignedTo: nobody at puremagic.com
ReportedBy: bearophile_hugs at eml.cc
--- Comment #0 from bearophile_hugs at eml.cc 2012-11-15 15:32:43 PST ---
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/chvkjlupnbewhfvemjst@forum.dlang.org
--
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
More information about the Digitalmars-d-bugs
mailing list