[llvm] [llvm] Update policy for Doxygen comments in the Coding Standards (PR #179898)

[Jonas Devlieghere via llvm-commits]

https://github.com/JDevlieghere created https://github.com/llvm/llvm-project/pull/179898

This PR updates the policy regarding Doxygen comments in the Coding Standards based on an RFC discussion on Discourse:

https://discourse.llvm.org/t/rfc-policy-for-doxygen-comments-in-lldb/89675/

>From 847f4cf7dfe0868eb1439bb7a184f87b6a6048b6 Mon Sep 17 00:00:00 2001
From: Jonas Devlieghere <jonas at devlieghere.com>
Date: Thu, 5 Feb 2026 10:51:35 +0100
Subject: [PATCH] [llvm] Update policy for Doxygen comments in the Coding
 Standards

This PR updates the policy regarding Doxygen comments in the Coding
Standards per the discussion on Discourse:

https://discourse.llvm.org/t/rfc-policy-for-doxygen-comments-in-lldb/89675/
---
 llvm/docs/CodingStandards.rst | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst
index 63f6663d687ea..8ea6625edc630 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 addtional information, such as intent, usage, or behavior that’s
+non-obvious.  Avoid restating information that can easily be inferred from the
+function signature.
 
 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++