Verified documentation comments

[bearophile]

Most of the slides of the recent 2012 LLVM Developers' Meeting 
are not yet available. But there are 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. Something similar is probably 
possible in D with DDocs:

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.
            ^


Currently in D if you have a documentation comment like this it 
generates no warnings or notes:

/**
* 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) {}

void main() {}


Bye,
bearophile