[llvm] r189704 - Remove the suggestion to not duplicate comments in header and

[Benjamin Kramer]

On Sat, Aug 31, 2013 at 1:34 AM, Chris Lattner <clattner at apple.com> wrote:
> On Aug 30, 2013, at 4:24 PM, Benjamin Kramer <benny.kra at gmail.com> wrote:
>> On 31.08.2013, at 01:06, Chris Lattner <sabre at nondot.org> wrote:
>>
>>> Author: lattner
>>> Date: Fri Aug 30 18:06:20 2013
>>> New Revision: 189704
>>>
>>> URL: http://llvm.org/viewvc/llvm-project?rev=189704&view=rev
>>> Log:
>>> Remove the suggestion to not duplicate comments in header and
>>> implementation files.  While doc generation systems don't need this,
>>> humans do benefit from it.  Not everyone reads all code through doxygen.
>>
>> I disagree.
>
> I expected this to start a discussion… this is good because the discussion never happened when gribozavr "Document current Doxygen use practices in Coding Standards" in r166378.
>
>> The big problem with duplicated comments is that now not just one comment gets out of date but we get two comments that diverge over time. I've seen this happening in LLVM several times. That alone is enough reason for not duplicating the comment.
>>
>> While it's true that few people actually read code through doxygen there are many tools (*cough* clang *cough*) that can consume doxygen comments and I hope that the usual editors will grow plugins that display them through libclang.
>
> I'm not fan of the comments diverging, and have seen this as well.  That said, not everyone uses Xcode or other libclang enabled tools.
>
> If you're passionate about solving this problem, why not enhance -Wdocumentation in clang to check that the two comment match up?

That's a really tricky problem. There are cases like the one Andy
pointed out (in the other discussion), where it makes sense to have
different comments on the declaration and implementation. The only
solution I see to this problem is using edit distances, with a huge
potential for false positives :(

- Ben