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: nob...@puremagic.com ReportedBy: bearophile_h...@eml.cc --- Comment #0 from bearophile_h...@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/chvkjlupnbewhfvem...@forum.dlang.org -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------