[llvm] 0462dfe - [llvm][docs] Refresh "Restrict Visibility" in Coding Standards (#150914)

[via llvm-commits]

Author: David Spickett
Date: 2025-07-28T16:04:07+01:00
New Revision: 0462dfe39f82ecb9fb7c9ddb15008e590b0c2924

URL: https://github.com/llvm/llvm-project/commit/0462dfe39f82ecb9fb7c9ddb15008e590b0c2924
DIFF: https://github.com/llvm/llvm-project/commit/0462dfe39f82ecb9fb7c9ddb15008e590b0c2924.diff

LOG: [llvm][docs] Refresh "Restrict Visibility" in Coding Standards (#150914)

No change of meaning, just formatting and an extra example to make it
easier to comprehend:
* Split separate, important points into their own paragraphs.
* Remove a contraction.
* Finally, show to to use "static" on a function. As before we just
showed why namespaces were bad, but not what you should do instead.

Added: 
    

Modified: 
    llvm/docs/CodingStandards.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst
index 732227b98ab9e..2dc3d7797b133 100644
--- a/llvm/docs/CodingStandards.rst
+++ b/llvm/docs/CodingStandards.rst
@@ -1594,20 +1594,25 @@ Restrict Visibility
 ^^^^^^^^^^^^^^^^^^^
 
 Functions and variables should have the most restricted visibility possible.
+
 For class members, that means using appropriate ``private``, ``protected``, or
-``public`` keyword to restrict their access. For non-member functions, variables,
-and classes, that means restricting visibility to a single ``.cpp`` file if it's
-not referenced outside that file.
+``public`` keyword to restrict their access.
+
+For non-member functions, variables, and classes, that means restricting
+visibility to a single ``.cpp`` file if it is not referenced outside that file.
 
 Visibility of file-scope non-member variables and functions can be restricted to
 the current translation unit by using either the ``static`` keyword or an anonymous
-namespace. Anonymous namespaces are a great language feature that tells the C++
+namespace.
+
+Anonymous namespaces are a great language feature that tells the C++
 compiler that the contents of the namespace are only visible within the current
 translation unit, allowing more aggressive optimization and eliminating the
-possibility of symbol name collisions.  Anonymous namespaces are to C++ as
-``static`` is to C functions and global variables.  While ``static`` is available
-in C++, anonymous namespaces are more general: they can make entire classes
-private to a file.
+possibility of symbol name collisions.
+
+Anonymous namespaces are to C++ as ``static`` is to C functions and global
+variables.  While ``static`` is available in C++, anonymous namespaces are more
+general: they can make entire classes private to a file.
 
 The problem with anonymous namespaces is that they naturally want to encourage
 indentation of their body, and they reduce locality of reference: if you see a
@@ -1653,10 +1658,17 @@ Avoid putting declarations other than classes into anonymous namespaces:
 
   } // namespace
 
-When you are looking at "``runHelper``" in the middle of a large C++ file,
-you have no immediate way to tell if this function is local to the file.  In
-contrast, when the function is marked static, you don't need to cross-reference
-faraway places in the file to tell that the function is local.
+When you are looking at ``runHelper`` in the middle of a large C++ file,
+you have no immediate way to tell if this function is local to the file.
+
+In contrast, when the function is marked static, you don't need to cross-reference
+faraway places in the file to tell that the function is local:
+
+.. code-block:: c++
+
+  static void runHelper() {
+    ...
+  }
 
 Don't Use Braces on Simple Single-Statement Bodies of if/else/loop Statements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^