From 89657f726f44e7cb8acd57dad62057c30be24197 Mon Sep 17 00:00:00 2001 From: Jeff Bailey Date: Wed, 18 Mar 2026 21:50:08 +0000 Subject: [PATCH] [libc][docs][NFC] Documentation consolidation and de-duplication (#187385) Summary: Integrated a series of quick documentation cleanups for LLVM-libc. This update focuses on de-duplicating core conventions (naming and namespaces) across multiple developer and contribution guides, and addresses empty platform stubs for UEFI. Changes: * libc/docs/contributing.rst: Removed duplicated code style rules and provided a link to dev/code_style.rst. * libc/docs/dev/clang_tidy_checks.rst: Removed redundant namespace explanations and linked to dev/code_style.rst. * libc/docs/dev/implementation_standard.rst: Removed repetitive notes about LIBC_NAMESPACE_DECL and linked to the authoritative reference. * libc/docs/uefi/support.rst & libc/docs/uefi/using.rst: Added early-stage bring-up warnings and pointed to the config directory for the source of truth. --- libc/docs/contributing.rst | 17 +++++------------ libc/docs/dev/clang_tidy_checks.rst | 7 +++---- libc/docs/dev/implementation_standard.rst | 6 +++--- libc/docs/uefi/support.rst | 6 ++++++ libc/docs/uefi/using.rst | 5 +++++ 5 files changed, 22 insertions(+), 19 deletions(-) diff --git a/libc/docs/contributing.rst b/libc/docs/contributing.rst index eea349c45b5c..a8d7fad67b81 100644 --- a/libc/docs/contributing.rst +++ b/libc/docs/contributing.rst @@ -18,18 +18,11 @@ a list of open projects that one can start with: ask if you can help take over. #. **Cleanup code-style** - The libc project follows the general - `LLVM style `_ but differs in a - few aspects: We use ``snake_case`` for non-constant variable and function - names,``CamelCase`` for internal type names (those which are not defined in a - public header), and ``CAPITALIZED_SNAKE_CASE`` for constants. When we started - working on the project, we started using the general LLVM style for - everything. However, for a short period, we switched to the style that is - currently followed by the `LLD project `_. - But, considering that we implement a lot of functions and types whose names - are prescribed by the standards, we have settled on the style described above. - However, we have not switched over to this style in all parts of the ``libc`` - directory. So, a simple but mechanical project would be to move the parts - following the old styles to the new style. + `LLVM style `_ with specific + conventions for naming (``snake_case`` for functions, ``CamelCase`` for + types). See the :ref:`code_style` page for the authoritative reference. + Mechanical projects to move parts following old styles to the current + conventions are welcome. #. **Implement Linux syscall wrappers** - A large portion of the POSIX API can be implemented as syscall wrappers on Linux. A good number have already been diff --git a/libc/docs/dev/clang_tidy_checks.rst b/libc/docs/dev/clang_tidy_checks.rst index 1ef2f60a472b..cf660dcf4267 100644 --- a/libc/docs/dev/clang_tidy_checks.rst +++ b/libc/docs/dev/clang_tidy_checks.rst @@ -43,10 +43,9 @@ 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. +All LLVM-libc implementation constructs must be enclosed in the +``LIBC_NAMESPACE_DECL`` namespace. See :ref:`code_style` for the full technical +rationale and macro definitions. This check ensures that top-level declarations in a translation unit are enclosed within the ``LIBC_NAMESPACE_DECL`` namespace. diff --git a/libc/docs/dev/implementation_standard.rst b/libc/docs/dev/implementation_standard.rst index 277fee9c1908..d06a997a3532 100644 --- a/libc/docs/dev/implementation_standard.rst +++ b/libc/docs/dev/implementation_standard.rst @@ -34,9 +34,9 @@ example. The ``isalpha`` function will be declared in an internal header file #endif LLVM_LIBC_SRC_CTYPE_ISALPHA_H -Notice that the ``isalpha`` function declaration is nested inside the namespace -``LIBC_NAMESPACE_DECL``. All implementation constructs in LLVM-libc are declared -within the namespace ``LIBC_NAMESPACE_DECL``. +All LLVM-libc implementation constructs must be enclosed in the +``LIBC_NAMESPACE_DECL`` namespace. See :ref:`code_style` for the full technical +rationale and macro definitions. ``.cpp`` File Structure ----------------------- diff --git a/libc/docs/uefi/support.rst b/libc/docs/uefi/support.rst index a13c683617bf..81067a73f3cc 100644 --- a/libc/docs/uefi/support.rst +++ b/libc/docs/uefi/support.rst @@ -9,6 +9,12 @@ Supported Functions The follow functions and headers are supported at least partially in UEFI. Some functions are implemented fully for UEFI. +.. note:: + LLVM-libc support for UEFI is currently in the early bring-up phase. The + tables below are placeholders; for the current source of truth on + implemented functions, please refer to ``libc/config/uefi/entrypoints.txt`` + in the source tree. + ctype.h ------- diff --git a/libc/docs/uefi/using.rst b/libc/docs/uefi/using.rst index b6c01411cb58..3f3ef9b5a2a8 100644 --- a/libc/docs/uefi/using.rst +++ b/libc/docs/uefi/using.rst @@ -11,3 +11,8 @@ Once you have finished :ref:`building` the UEFI C library it can be used to run libc or libm functions inside of UEFI Images. Currently, not all C standard functions are supported in UEFI. Consult the :ref:`list of supported functions` for a comprehensive list. + +.. note:: + LLVM-libc support for UEFI is currently in the early bring-up phase. For + the current source of truth on implemented functions, please refer to + ``libc/config/uefi/entrypoints.txt`` in the source tree.