diff --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst
index 63f6663d687e..593388db7ddf 100644
--- a/llvm/docs/CodingStandards.rst
+++ b/llvm/docs/CodingStandards.rst
@@ -278,11 +278,23 @@ 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).  Avoid restating 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.
+member and non-member functions).  Avoid restating the information that can be
+inferred from the API name or signature.  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.
+
+A minimal documentation comment:
+
+.. code-block:: c++
+
+  /// Sets the xyzzy property to \p Baz.
+  void setXyzzy(bool Baz);
+
+Only include code examples, function parameters and return values when it
+provides additional information, such as intent, usage, or behavior that’s
+non-obvious.  Use descriptive function and argument names to
+eliminate the need for documentation comments when possible.
 
 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
@@ -298,13 +310,6 @@ respectively.
 To describe function return value, start a new paragraph with the ``\returns``
 command.
 
-A minimal documentation comment:
-
-.. code-block:: c++
-
-  /// Sets the xyzzy property to \p Baz.
-  void setXyzzy(bool Baz);
-
 A documentation comment that uses all Doxygen features in a preferred way:
 
 .. code-block:: c++