[cfe-dev] Doxygen comments duplicated in Clang source files : OK to delete them?

[Chris Lattner]

On Jul 3, 2012, at 5:07 PM, Chandler Carruth wrote:
> On Tue, Jul 3, 2012 at 4:33 PM, James Dennett <jdennett at google.com> wrote:
> As I clean up a lot of Clang's comments for Doxygen's consumption, I'm
> hitting one issue repeatedly: a lot of the documentation is cut+pasted
> between the header file and the associated source file.  Apart from
> confusing some configurations of Doxygen (which concatenate the docs,
> giving duplication in the output), this inevitably leads to bitrot and
> divergence.
> 
> I think the duplication is really bad, and I have a moderately strong preference for how to de-duplicate:

Sorry to be a contrarian again, but I find it really useful to have the copy-and-pasted doc comments on methods implementations in the .cpp files as well as on the prototypes in the header.  It is really common for me to be working on a .cpp file without the header open, and losing the doc comments is a big loss.

If the goal is to avoid bitrot and divergence, why not make the doc comment parser note divergence and warn about it?

-Chris
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120703/546ac296/attachment.html>