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
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 next sibling parent 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
prev sibling 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 next 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 "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