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

[James Dennett]

On Tue, Jul 3, 2012 at 7:30 PM, Chris Lattner <clattner at apple.com> wrote:
> 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.

That's very interesting (in that it's the first time I've heard this
argument, and it runs counter to my own experience of what works
well).  I'll have to think about what's best to do there.  One thought
is to keep whatever you want in the implementation but *not* to mark
it up as a Doxygen comment for extraction, though that might make your
hypothetical sync tool a little more complicated.

(I still need to look into how it is that my Doxygen runs all end up
with duplication in the output, whereas those on the Clang website
don't.  That might or might not be because I'm using more recent
builds of Doxygen.)

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

Divergence is the smallest of several problems.

That's an interesting idea to address that one piece though.  I think
we'd need something more than that -- we'd need a re-writer to sync
the comments, as otherwise the effort needed to do so will be
untenable.  And of course then we'd either need to decide that one
place is canonical, or have some other way to resolve conflicts.

However: My primary goal is to make Clang's documentation so good that
it's possible, most of the time, to program to the published
interfaces without needing to rely on implementation details or having
to ask questions for even basic uses.  I tend to be opposed to
anything that makes maintaining documentation more work for
developers; empirically they're already not keeping up with the
documentation workload, I'd prefer to reduce the overhead and focus on
writing more useful material.

I'll go away and think about your stated preference for duplication,
possibly over something peaty.

-- James