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

[James Dennett]

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.

Taking one example:
clang::TokenConcatenation::IsIdentifierStringPrefix has documentation
in the header file Lex/TokenConcatenation.h:
    /// \brief Return true if the spelling of the token is literally 'L', 'u',
    /// 'U', or 'u8'.
Whereas in the source file Lex/TokenConcatenation.cpp it is documented as:
    /// IsIdentifierStringPrefix - Return true if the spelling of the token
    /// is literally 'L', 'u', 'U', or 'u8'. Including raw versions.
The latter is closer to correct, but still wrong; if
LangOpts.CPlusPlus0x isn't enabled then it checks only for 'L', which
is entirely reasonable (given that that's the only valid
encoding-prefix from C++98).

Obviously I can fix up the documentation for that one function, but my
bigger-picture question is this: is there any good reason for me not
to delete the duplicated documentation from the source files in this
and other cases?  Or a related question: can anyone shed any light on
why this duplication is there in the first place?

-- James