• d-bugmail puremagic.com (84/84) Nov 15 2012 http://d.puremagic.com/issues/show_bug.cgi?id=9032

d-bugmail puremagic.com writes:

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 puremagic.com
        ReportedBy: bearophile_hugs eml.cc


--- Comment #0 from bearophile_hugs 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: -------