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

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

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

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.

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

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

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