[docs] Add guidance on duplicating doc comments to CodingStandards

[asb]

Summary

Duplicating documentation comments for overridden methods adds a maintenance burden, and should be avoided. Discussed on llvm-dev: http://lists.llvm.org/pipermail/llvm-dev/2018-January/120882.html

[reames]

docs/CodingStandards.rst

324

I'd suggest reframing this to focus on what should you document for the override version. i.e. When documenting override methods, highlight the differences with parent implementation. Instead of duplicating the existing documentation, refer to it if needed. If the documentation for the overridden method is sufficient to document the override's behaviour, omit documentation of the override.

[echristo]

docs/CodingStandards.rst

324

+1

[lattner]

Personally, I don't see the harm in duplicating the comments, and they are useful when you're not using doxygen or some other tool. You're talking about the overriden method situation, but another common one is when you define a class in an anonymous namespace and then implement it later in the same file. The implementation should certainly have a doc comment on it, and if it helps to understand the overview of what the struct is doing, then it makes sense to document it in the class definition as well.

Yes, of course the comments can get out of date, but so can code. I haven't heard of this being a code maintenance problem in practice.

-Chris

[lattner]

Here's a different way to interpret the current situation: instead of seeing the current behavior as "inconsistent", you could see it as "duplication only making sense in some cases". Realistically though, I agree that the code base is probably inconsistent as it is written by lots of people with different practices.

If you're interested in making this situation better, it would probably be effective to teach clang-tidy to complain about duplicated comment blocks that are larger than a certain threshold but slightly different.

-Chris

docs/CodingStandards.rst

 Use the ``\file`` command to turn the standard file header into a file-level
 comment.
 
 Include descriptive paragraphs for all public interfaces (public classes,
 member and non-member functions).  Don't just restate the information that can
 be inferred from the API name.  The first sentence (or a paragraph beginning
 with ``\brief``) is used as an abstract. Try to use a single sentence as the
 ``\brief`` adds visual clutter.  Put detailed discussion into separate
-paragraphs.
+paragraphs. Avoid duplicating documentation for overridden methods. When
+extending documentation from the superclass, the ``\copydoc name`` command can
+be used.
 
 To refer to parameter names inside a paragraph, use the ``\p name`` command.
 Don't use the ``\arg name`` command since it starts a new paragraph that
 contains documentation for the parameter.
 
 Wrap non-inline code examples in ``\code ... \endcode``.
 
 To document a function parameter, start a new paragraph with the