[PATCH] D42850: [docs] Add guidance on duplicating doc comments to CodingStandards

[Alex Bradbury via Phabricator via llvm-commits]

asb created this revision.
asb added reviewers: MatzeB, theraven, reames.
Herald added a subscriber: llvm-commits.

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


Repository:
  rL LLVM

https://reviews.llvm.org/D42850

Files:
  docs/CodingStandards.rst


Index: docs/CodingStandards.rst
===================================================================
--- docs/CodingStandards.rst
+++ docs/CodingStandards.rst
@@ -321,7 +321,9 @@
 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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D42850.132615.patch
Type: text/x-patch
Size: 737 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20180202/909bfeee/attachment.bin>