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

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

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

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.

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

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