[libc-commits] [libc] [libc][docs] Update clang-tidy checks page (PR #185923)

[Petter Berntsson via libc-commits]

https://github.com/petbernt created https://github.com/llvm/llvm-project/pull/185923

Document layered .clang-tidy config, update llvmlibc-* check names, and drop stale TODO

>From 03274c88d5556c5028c617e7986bd490b581995d Mon Sep 17 00:00:00 2001
From: Petter Berntsson <petter.berntsson at arm.com>
Date: Wed, 11 Mar 2026 15:39:29 +0000
Subject: [PATCH] [libc][docs] Update clang-tidy checks page

Document layered .clang-tidy config, update llvmlibc-* check names, and drop stale TODO
---
 libc/docs/contributing.rst          |  9 +++---
 libc/docs/dev/clang_tidy_checks.rst | 47 ++++++++++++++++++-----------
 libc/docs/dev/code_style.rst        |  4 ---
 3 files changed, 35 insertions(+), 25 deletions(-)

diff --git a/libc/docs/contributing.rst b/libc/docs/contributing.rst
index a674290cf6dc0..eea349c45b5cc 100644
--- a/libc/docs/contributing.rst
+++ b/libc/docs/contributing.rst
@@ -38,10 +38,11 @@ a list of open projects that one can start with:
    implemented.
 
 #. **Update the clang-tidy lint rules and use them in the build and/or CI** -
-   Currently, the :ref:`clang_tidy_checks` have gone stale and are mostly unused
-   by the developers and on the CI builders. This project is about updating
-   them and reintegrating them back with the build and running them on the
-   CI builders.
+   The libc project has a set of clang-tidy checks (see :ref:`clang_tidy_checks`)
+   but they are not enabled by default. They can be enabled by configuring with
+   ``-DLLVM_LIBC_ENABLE_LINTING=ON`` (or by setting ``LLVM_LIBC_CLANG_TIDY``) and
+   running the ``libc-lint`` build target. This project is about keeping the
+   checks up to date and reintegrating them into the build and CI.
 
 #. **double and higher precision math functions** - These are under active
    development but you can take a shot at those not yet implemented. See
diff --git a/libc/docs/dev/clang_tidy_checks.rst b/libc/docs/dev/clang_tidy_checks.rst
index 91d415a2e0d47..1ef2f60a472b1 100644
--- a/libc/docs/dev/clang_tidy_checks.rst
+++ b/libc/docs/dev/clang_tidy_checks.rst
@@ -3,17 +3,25 @@
 LLVM libc clang-tidy checks
 ===========================
 
+Configuration
+-------------
 
-.. warning::
-  This page is severely out of date. Much of the information it contains may be
-  incorrect. Please only remove this warning once the page has been updated.
+LLVM libc uses layered ``.clang-tidy`` configuration files:
 
-These are the clang-tidy checks designed to help enforce implementation
-standards.
-The configuration file is ``src/.clang-tidy``.
+- ``libc/.clang-tidy``: baseline checks for the ``libc`` subtree (currently
+  focuses on identifier naming conventions).
+- ``libc/src/.clang-tidy``: adds LLVM-libc-specific checks (``llvmlibc-*``) for
+  implementation code under ``libc/src`` and also enables
+  ``readability-identifier-naming`` and ``llvm-header-guard``. Diagnostics from
+  ``llvmlibc-*`` checks are treated as errors.
+
+LLVM-libc checks
+----------------
+
+restrict-system-libc-headers
+----------------------------
+Check name: ``llvmlibc-restrict-system-libc-headers``.
 
-restrict-system-libc-header
----------------------------
 One of libc-project’s design goals is to use kernel headers and compiler
 provided headers to prevent code duplication on a per platform basis. This
 presents a problem when writing implementations since system libc headers are
@@ -31,17 +39,17 @@ libc implementation.
    #include <stddef.h>           // Allowed because it is provided by the compiler.
    #include "internal/stdio.h"   // Allowed because it is NOT part of system libc.
 
-
 implementation-in-namespace
 ---------------------------
+Check name: ``llvmlibc-implementation-in-namespace``.
 
 It is part of our implementation standards that all implementation pieces live
 under the ``LIBC_NAMESPACE_DECL`` namespace. This prevents pollution of the
 global namespace. Without a formal check to ensure this, an implementation
 might compile and pass unit tests, but not produce a usable libc function.
 
-This check that ensures any function call resolves to a function within the
-``LIBC_NAMESPACE_DECL`` namespace.
+This check ensures that top-level declarations in a translation unit are
+enclosed within the ``LIBC_NAMESPACE_DECL`` namespace.
 
 .. code-block:: c++
 
@@ -64,14 +72,10 @@ This check that ensures any function call resolves to a function within the
         void LLVM_LIBC_ENTRYPOINT(strcpy)(char *dest, const char *src) {}
     }
 
-..
-  TODO(97655): The clang-tidy check should be updated to ensure the namespace
-  declaration uses LIBC_NAMESPACE_DECL as opposed to LIBC_NAMESPACE. The former
-  should be used for accessing globals in LIBC_NAMESPACE rather than declaration.
-
-
 callee-namespace
 ----------------
+Check name: ``llvmlibc-callee-namespace``.
+
 LLVM-libc is distinct because it is designed to maintain interoperability with
 other libc libraries, including the one that lives on the system. This feature
 creates some uncertainty about which library a call resolves to especially when
@@ -105,3 +109,12 @@ are always external and can be intercepted.
     ::malloc(10);
 
     } // namespace LIBC_NAMESPACE_DECL
+
+
+inline-function-decl
+--------------------
+Check name: ``llvmlibc-inline-function-decl``.
+
+LLVM libc uses the ``LIBC_INLINE`` macro to tag inline function declarations in
+headers. This check enforces that any inline function declaration in a header
+begins with ``LIBC_INLINE`` and provides a fix-it to insert the macro.
diff --git a/libc/docs/dev/code_style.rst b/libc/docs/dev/code_style.rst
index f88d82feea367..7c53ad30a5d4d 100644
--- a/libc/docs/dev/code_style.rst
+++ b/libc/docs/dev/code_style.rst
@@ -289,7 +289,3 @@ Example usage:
 Having hidden visibility on the namespace ensures extern declarations in a given TU
 have known visibility and never generate GOT indirections. The attribute guarantees
 this independently of global compile options and build systems.
-
-..
-  TODO(97655): We should have a clang-tidy check to enforce this and a
-  fixit implementation.