www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Verified documentation comments

reply "bearophile" <bearophileHUGS lycos.com> writes:
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
Nov 15 2012
next sibling parent reply Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 11/15/12, bearophile <bearophileHUGS lycos.com> wrote:

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


So you open dlang.org, hit the edit button, and fix it. Doing
semantics in comments is beyond overkill.

And soon enough we won't have to use "---"-style comments for code
snippets anymore because the compiler will auto-insert the code from
the next ddoc'ed unittests as ddoc'ed code samples (there is a pull
ready but it requires a review, and perhaps a rewrite since the
implementation is cheating a little bit).
Nov 15 2012
next sibling parent reply Marco Leise <Marco.Leise gmx.de> writes:
Am Thu, 15 Nov 2012 20:15:15 +0100
schrieb Andrej Mitrovic <andrej.mitrovich gmail.com>:


 Doing semantics in comments is beyond overkill.


They are DDoc and attached to a symbol. I've seen IDEs give
information on errors in documentation comments on the fly.
If at some point we can also automatically document thrown
exceptions I'm happy :)
I'm all for compiler warnings where they are cheap. Why wait
for someone to tell you, that your documentation has obvious
errors that could have been statically checked during its
generation ?
Let's add this as a nice-to-have on the new Wiki. Someone who
is interested in hacking on DMD can pick it up then.

-- 
Marco
Nov 15 2012
next sibling parent "Brian Schott" <briancschott gmail.com> writes:
On Thursday, 15 November 2012 at 20:58:55 UTC, Marco Leise wrote:

 Am Thu, 15 Nov 2012 20:15:15 +0100
 schrieb Andrej Mitrovic <andrej.mitrovich gmail.com>:


 Doing semantics in comments is beyond overkill.


 They are DDoc and attached to a symbol. I've seen IDEs give
 information on errors in documentation comments on the fly.
 If at some point we can also automatically document thrown
 exceptions I'm happy :)
 I'm all for compiler warnings where they are cheap. Why wait
 for someone to tell you, that your documentation has obvious
 errors that could have been statically checked during its
 generation ?
 Let's add this as a nice-to-have on the new Wiki. Someone who
 is interested in hacking on DMD can pick it up then.


One way to solve this and similar issues may be to add D support 
to PMD. (http://pmd.sourceforge.net/). Many rules can be created 
as XPath expressions, so if someone wants a new check on their 
code, they can just write it. A side effect of doing this is that 
we'd have a javacc-compatible grammar for D.
Nov 15 2012
prev sibling parent "bearophile" <bearophileHUGS lycos.com> writes:
Marco Leise:


 Let's add this as a nice-to-have on the new Wiki. Someone who
 is interested in hacking on DMD can pick it up then.


I have added a suggestion in Bugzilla:
http://d.puremagic.com/issues/show_bug.cgi?id=9032

Bye,
bearophile
Nov 15 2012
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2012-11-15 20:15, Andrej Mitrovic wrote:


 So you open dlang.org, hit the edit button, and fix it. Doing
 semantics in comments is beyond overkill.


I would rather say that this is the next logical step when having a 
compiler built with a modularized architecture that is readable and 
maintainable, a.k.a Clang. It's just connecting the dots.

-- 
/Jacob Carlborg
Nov 15 2012
prev sibling parent "Rob T" <rob ucora.com> writes:
On Thursday, 15 November 2012 at 18:45:58 UTC, bearophile wrote:

 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


Another improvement would be place holders for the parameters 
that get filled in automatically. It's extremely tedious, 
redundant, and error prone to manually name parameters inside the 
document comments.

I like the idea of embedded documentation, it's nice and has a 
ton of potential, and can be made a whole lot better.

--rt
Nov 17 2012