[libc-commits] [libc] [libc][docs] use docgen to generate stdbit rst docs (PR #88540)
Michael Flanders via libc-commits
libc-commits at lists.llvm.org
Fri Apr 12 10:27:26 PDT 2024
https://github.com/Flandini created https://github.com/llvm/llvm-project/pull/88540
Closes #88066.
Compared to before, the function names in the stdbit table are sorted by function name, not order-of-appearance in the standard.
Adds some checks to docgen.py for conditions that tripped me up.
Add code to docgen.py to add the include of the `|check|` rewriter, since all other generated files need it.
Adding @nickdesaulniers for review.
>From c7309c31d8e5052d22559366bd63c6ca87153497 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Fri, 12 Apr 2024 10:13:08 -0700
Subject: [PATCH] [libc][docs] use docgen to generate stdbit rst docs
---
libc/docs/stdbit.rst | 350 +++++++++++++++++++++-------------
libc/utils/docgen/docgen.py | 8 +
libc/utils/docgen/stdbit.json | 234 +++++++++++++++++++++++
3 files changed, 461 insertions(+), 131 deletions(-)
create mode 100644 libc/utils/docgen/stdbit.json
diff --git a/libc/docs/stdbit.rst b/libc/docs/stdbit.rst
index d42f7938246293..0a12b2b6d7b513 100644
--- a/libc/docs/stdbit.rst
+++ b/libc/docs/stdbit.rst
@@ -1,135 +1,223 @@
-=========================
-Bitwise Utility Functions
-=========================
-
.. include:: check.rst
----------------
-Source Location
----------------
-
-- The main source for bitwise utility functions is located at:
- ``libc/src/stdbit``.
-
-- The source for internal helpers used to implement these is located at:
- ``libc/src/__support/CPP/bit.h``.
-
-- The tests are located at:
- ``libc/test/src/stdbit/``, ``libc/test/include/stdbit_test.cpp``, and
- ``src/__support/CPP/bit_test.cpp``.
-
----------------------
-Implementation Status
----------------------
-
-Functions
-=========
-
-..
- Do not order these, they are as they appear in the standard.
-
-============================ =========
-Function Name Available
-============================ =========
-stdc_leading_zeros_uc |check|
-stdc_leading_zeros_us |check|
-stdc_leading_zeros_ui |check|
-stdc_leading_zeros_ul |check|
-stdc_leading_zeros_ull |check|
-stdc_leading_ones_uc |check|
-stdc_leading_ones_us |check|
-stdc_leading_ones_ui |check|
-stdc_leading_ones_ul |check|
-stdc_leading_ones_ull |check|
-stdc_trailing_zeros_uc |check|
-stdc_trailing_zeros_us |check|
-stdc_trailing_zeros_ui |check|
-stdc_trailing_zeros_ul |check|
-stdc_trailing_zeros_ull |check|
-stdc_trailing_ones_uc |check|
-stdc_trailing_ones_us |check|
-stdc_trailing_ones_ui |check|
-stdc_trailing_ones_ul |check|
-stdc_trailing_ones_ull |check|
-stdc_first_leading_zero_uc |check|
-stdc_first_leading_zero_us |check|
-stdc_first_leading_zero_ui |check|
-stdc_first_leading_zero_ul |check|
-stdc_first_leading_zero_ull |check|
-stdc_first_leading_one_uc |check|
-stdc_first_leading_one_us |check|
-stdc_first_leading_one_ui |check|
-stdc_first_leading_one_ul |check|
-stdc_first_leading_one_ull |check|
-stdc_first_trailing_zero_uc |check|
-stdc_first_trailing_zero_us |check|
-stdc_first_trailing_zero_ui |check|
-stdc_first_trailing_zero_ul |check|
-stdc_first_trailing_zero_ull |check|
-stdc_first_trailing_one_uc |check|
-stdc_first_trailing_one_us |check|
-stdc_first_trailing_one_ui |check|
-stdc_first_trailing_one_ul |check|
-stdc_first_trailing_one_ull |check|
-stdc_count_zeros_uc |check|
-stdc_count_zeros_us |check|
-stdc_count_zeros_ui |check|
-stdc_count_zeros_ul |check|
-stdc_count_zeros_ull |check|
-stdc_count_ones_uc |check|
-stdc_count_ones_us |check|
-stdc_count_ones_ui |check|
-stdc_count_ones_ul |check|
-stdc_count_ones_ull |check|
-stdc_has_single_bit_uc |check|
-stdc_has_single_bit_us |check|
-stdc_has_single_bit_ui |check|
-stdc_has_single_bit_ul |check|
-stdc_has_single_bit_ull |check|
-stdc_bit_width_uc |check|
-stdc_bit_width_us |check|
-stdc_bit_width_ui |check|
-stdc_bit_width_ul |check|
-stdc_bit_width_ull |check|
-stdc_bit_floor_uc |check|
-stdc_bit_floor_us |check|
-stdc_bit_floor_ui |check|
-stdc_bit_floor_ul |check|
-stdc_bit_floor_ull |check|
-stdc_bit_ceil_uc |check|
-stdc_bit_ceil_us |check|
-stdc_bit_ceil_ui |check|
-stdc_bit_ceil_ul |check|
-stdc_bit_ceil_ull |check|
-============================ =========
-
-
-Macros
-======
+stdbit.h Functions
+==================
-========================= =========
-Macro Name Available
-========================= =========
-__STDC_VERSION_STDBIT_H__ |check|
-__STDC_ENDIAN_LITTLE__ |check|
-__STDC_ENDIAN_BIG__ |check|
-__STDC_ENDIAN_NATIVE__ |check|
-stdc_leading_zeros |check|
-stdc_leading_ones |check|
-stdc_trailing_zeros |check|
-stdc_trailing_ones |check|
-stdc_first_leading_zero |check|
-stdc_first_leading_one |check|
-stdc_first_trailing_zero |check|
-stdc_first_trailing_one |check|
-stdc_count_zeros |check|
-stdc_count_ones |check|
-stdc_has_single_bit |check|
-stdc_bit_width |check|
-stdc_bit_floor |check|
-stdc_bit_ceil |check|
-========================= =========
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
-Standards
-=========
-stdbit.h was specified as part of C23 in section 7.18 "Bit and byte utilities."
+ * - Function
+ - Implemented
+ - Standard
+ * - stdc_bit_ceil_uc
+ - |check|
+ - 7.18.16
+ * - stdc_bit_ceil_ui
+ - |check|
+ - 7.18.16
+ * - stdc_bit_ceil_ul
+ - |check|
+ - 7.18.16
+ * - stdc_bit_ceil_ull
+ - |check|
+ - 7.18.16
+ * - stdc_bit_ceil_us
+ - |check|
+ - 7.18.16
+ * - stdc_bit_floor_uc
+ - |check|
+ - 7.18.15
+ * - stdc_bit_floor_ui
+ - |check|
+ - 7.18.15
+ * - stdc_bit_floor_ul
+ - |check|
+ - 7.18.15
+ * - stdc_bit_floor_ull
+ - |check|
+ - 7.18.15
+ * - stdc_bit_floor_us
+ - |check|
+ - 7.18.15
+ * - stdc_bit_width_uc
+ - |check|
+ - 7.18.14
+ * - stdc_bit_width_ui
+ - |check|
+ - 7.18.14
+ * - stdc_bit_width_ul
+ - |check|
+ - 7.18.14
+ * - stdc_bit_width_ull
+ - |check|
+ - 7.18.14
+ * - stdc_bit_width_us
+ - |check|
+ - 7.18.14
+ * - stdc_count_ones_uc
+ - |check|
+ - 7.18.12
+ * - stdc_count_ones_ui
+ - |check|
+ - 7.18.12
+ * - stdc_count_ones_ul
+ - |check|
+ - 7.18.12
+ * - stdc_count_ones_ull
+ - |check|
+ - 7.18.12
+ * - stdc_count_ones_us
+ - |check|
+ - 7.18.12
+ * - stdc_count_zeros_uc
+ - |check|
+ - 7.18.11
+ * - stdc_count_zeros_ui
+ - |check|
+ - 7.18.11
+ * - stdc_count_zeros_ul
+ - |check|
+ - 7.18.11
+ * - stdc_count_zeros_ull
+ - |check|
+ - 7.18.11
+ * - stdc_count_zeros_us
+ - |check|
+ - 7.18.11
+ * - stdc_first_leading_one_uc
+ - |check|
+ - 7.18.8
+ * - stdc_first_leading_one_ui
+ - |check|
+ - 7.18.8
+ * - stdc_first_leading_one_ul
+ - |check|
+ - 7.18.8
+ * - stdc_first_leading_one_ull
+ - |check|
+ - 7.18.8
+ * - stdc_first_leading_one_us
+ - |check|
+ - 7.18.8
+ * - stdc_first_leading_zero_uc
+ - |check|
+ - 7.18.7
+ * - stdc_first_leading_zero_ui
+ - |check|
+ - 7.18.7
+ * - stdc_first_leading_zero_ul
+ - |check|
+ - 7.18.7
+ * - stdc_first_leading_zero_ull
+ - |check|
+ - 7.18.7
+ * - stdc_first_leading_zero_us
+ - |check|
+ - 7.18.7
+ * - stdc_first_trailing_one_uc
+ - |check|
+ - 7.18.10
+ * - stdc_first_trailing_one_ui
+ - |check|
+ - 7.18.10
+ * - stdc_first_trailing_one_ul
+ - |check|
+ - 7.18.10
+ * - stdc_first_trailing_one_ull
+ - |check|
+ - 7.18.10
+ * - stdc_first_trailing_one_us
+ - |check|
+ - 7.18.10
+ * - stdc_first_trailing_zero_uc
+ - |check|
+ - 7.18.9
+ * - stdc_first_trailing_zero_ui
+ - |check|
+ - 7.18.9
+ * - stdc_first_trailing_zero_ul
+ - |check|
+ - 7.18.9
+ * - stdc_first_trailing_zero_ull
+ - |check|
+ - 7.18.9
+ * - stdc_first_trailing_zero_us
+ - |check|
+ - 7.18.9
+ * - stdc_has_single_bit_uc
+ - |check|
+ - 7.18.13
+ * - stdc_has_single_bit_ui
+ - |check|
+ - 7.18.13
+ * - stdc_has_single_bit_ul
+ - |check|
+ - 7.18.13
+ * - stdc_has_single_bit_ull
+ - |check|
+ - 7.18.13
+ * - stdc_has_single_bit_us
+ - |check|
+ - 7.18.13
+ * - stdc_leading_ones_uc
+ - |check|
+ - 7.18.4
+ * - stdc_leading_ones_ui
+ - |check|
+ - 7.18.4
+ * - stdc_leading_ones_ul
+ - |check|
+ - 7.18.4
+ * - stdc_leading_ones_ull
+ - |check|
+ - 7.18.4
+ * - stdc_leading_ones_us
+ - |check|
+ - 7.18.4
+ * - stdc_leading_zeros_uc
+ - |check|
+ - 7.18.3
+ * - stdc_leading_zeros_ui
+ - |check|
+ - 7.18.3
+ * - stdc_leading_zeros_ul
+ - |check|
+ - 7.18.3
+ * - stdc_leading_zeros_ull
+ - |check|
+ - 7.18.3
+ * - stdc_leading_zeros_us
+ - |check|
+ - 7.18.3
+ * - stdc_trailing_ones_uc
+ - |check|
+ - 7.18.6
+ * - stdc_trailing_ones_ui
+ - |check|
+ - 7.18.6
+ * - stdc_trailing_ones_ul
+ - |check|
+ - 7.18.6
+ * - stdc_trailing_ones_ull
+ - |check|
+ - 7.18.6
+ * - stdc_trailing_ones_us
+ - |check|
+ - 7.18.6
+ * - stdc_trailing_zeros_uc
+ - |check|
+ - 7.18.5
+ * - stdc_trailing_zeros_ui
+ - |check|
+ - 7.18.5
+ * - stdc_trailing_zeros_ul
+ - |check|
+ - 7.18.5
+ * - stdc_trailing_zeros_ull
+ - |check|
+ - 7.18.5
+ * - stdc_trailing_zeros_us
+ - |check|
+ - 7.18.5
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 36eb409421b4f5..23d45305fe513c 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -28,6 +28,13 @@ def is_implemented(hname: str, fname: str) -> bool:
"src",
hname.rstrip(".h")
)
+
+ if not path.exists():
+ raise FileNotFoundError(f"implementation dir does not exist: {path}")
+
+ if not path.is_dir():
+ raise NotADirectoryError(f"implementation dir is not a dir: {path}")
+
# Recursively search for the target source file in the subdirectories under
# libc/src/{hname}.
for _ in path.glob("**/" + fname + ".cpp"):
@@ -53,6 +60,7 @@ def print_functions(header: str, functions: Dict):
def print_header(header: str, api: Dict):
+ print(".. include:: check.rst\n")
fns = f"{header} Functions"
print(fns)
print("=" * (len(fns)))
diff --git a/libc/utils/docgen/stdbit.json b/libc/utils/docgen/stdbit.json
new file mode 100644
index 00000000000000..9dda0cb0f5383a
--- /dev/null
+++ b/libc/utils/docgen/stdbit.json
@@ -0,0 +1,234 @@
+{
+ "macros": [
+ "__STDC_VERSION_STDBIT_H__",
+ "__STDC_ENDIAN_LITTLE__",
+ "__STDC_ENDIAN_BIG__",
+ "__STDC_ENDIAN_NATIVE__",
+ "stdc_leading_zeros",
+ "stdc_leading_ones",
+ "stdc_trailing_zeros",
+ "stdc_trailing_ones",
+ "stdc_first_leading_zero",
+ "stdc_first_leading_one",
+ "stdc_first_trailing_zero",
+ "stdc_first_trailing_one",
+ "stdc_count_zeros",
+ "stdc_count_ones",
+ "stdc_has_single_bit",
+ "stdc_bit_width",
+ "stdc_bit_floor",
+ "stdc_bit_ceil"
+ ],
+ "functions": {
+ "stdc_leading_zeros_uc": {
+ "defined": "7.18.3"
+ },
+ "stdc_leading_zeros_us": {
+ "defined": "7.18.3"
+ },
+ "stdc_leading_zeros_ui": {
+ "defined": "7.18.3"
+ },
+ "stdc_leading_zeros_ul": {
+ "defined": "7.18.3"
+ },
+ "stdc_leading_zeros_ull": {
+ "defined": "7.18.3"
+ },
+ "stdc_leading_ones_uc": {
+ "defined": "7.18.4"
+ },
+ "stdc_leading_ones_us": {
+ "defined": "7.18.4"
+ },
+ "stdc_leading_ones_ui": {
+ "defined": "7.18.4"
+ },
+ "stdc_leading_ones_ul": {
+ "defined": "7.18.4"
+ },
+ "stdc_leading_ones_ull": {
+ "defined": "7.18.4"
+ },
+ "stdc_trailing_zeros_uc": {
+ "defined": "7.18.5"
+ },
+ "stdc_trailing_zeros_us": {
+ "defined": "7.18.5"
+ },
+ "stdc_trailing_zeros_ui": {
+ "defined": "7.18.5"
+ },
+ "stdc_trailing_zeros_ul": {
+ "defined": "7.18.5"
+ },
+ "stdc_trailing_zeros_ull": {
+ "defined": "7.18.5"
+ },
+ "stdc_trailing_ones_uc": {
+ "defined": "7.18.6"
+ },
+ "stdc_trailing_ones_us": {
+ "defined": "7.18.6"
+ },
+ "stdc_trailing_ones_ui": {
+ "defined": "7.18.6"
+ },
+ "stdc_trailing_ones_ul": {
+ "defined": "7.18.6"
+ },
+ "stdc_trailing_ones_ull": {
+ "defined": "7.18.6"
+ },
+ "stdc_first_leading_zero_uc": {
+ "defined": "7.18.7"
+ },
+ "stdc_first_leading_zero_us": {
+ "defined": "7.18.7"
+ },
+ "stdc_first_leading_zero_ui": {
+ "defined": "7.18.7"
+ },
+ "stdc_first_leading_zero_ul": {
+ "defined": "7.18.7"
+ },
+ "stdc_first_leading_zero_ull": {
+ "defined": "7.18.7"
+ },
+ "stdc_first_leading_one_uc": {
+ "defined": "7.18.8"
+ },
+ "stdc_first_leading_one_us": {
+ "defined": "7.18.8"
+ },
+ "stdc_first_leading_one_ui": {
+ "defined": "7.18.8"
+ },
+ "stdc_first_leading_one_ul": {
+ "defined": "7.18.8"
+ },
+ "stdc_first_leading_one_ull": {
+ "defined": "7.18.8"
+ },
+ "stdc_first_trailing_zero_uc": {
+ "defined": "7.18.9"
+ },
+ "stdc_first_trailing_zero_us": {
+ "defined": "7.18.9"
+ },
+ "stdc_first_trailing_zero_ui": {
+ "defined": "7.18.9"
+ },
+ "stdc_first_trailing_zero_ul": {
+ "defined": "7.18.9"
+ },
+ "stdc_first_trailing_zero_ull": {
+ "defined": "7.18.9"
+ },
+ "stdc_first_trailing_one_uc": {
+ "defined": "7.18.10"
+ },
+ "stdc_first_trailing_one_us": {
+ "defined": "7.18.10"
+ },
+ "stdc_first_trailing_one_ui": {
+ "defined": "7.18.10"
+ },
+ "stdc_first_trailing_one_ul": {
+ "defined": "7.18.10"
+ },
+ "stdc_first_trailing_one_ull": {
+ "defined": "7.18.10"
+ },
+ "stdc_count_zeros_uc": {
+ "defined": "7.18.11"
+ },
+ "stdc_count_zeros_us": {
+ "defined": "7.18.11"
+ },
+ "stdc_count_zeros_ui": {
+ "defined": "7.18.11"
+ },
+ "stdc_count_zeros_ul": {
+ "defined": "7.18.11"
+ },
+ "stdc_count_zeros_ull": {
+ "defined": "7.18.11"
+ },
+ "stdc_count_ones_uc": {
+ "defined": "7.18.12"
+ },
+ "stdc_count_ones_us": {
+ "defined": "7.18.12"
+ },
+ "stdc_count_ones_ui": {
+ "defined": "7.18.12"
+ },
+ "stdc_count_ones_ul": {
+ "defined": "7.18.12"
+ },
+ "stdc_count_ones_ull": {
+ "defined": "7.18.12"
+ },
+ "stdc_has_single_bit_uc": {
+ "defined": "7.18.13"
+ },
+ "stdc_has_single_bit_us": {
+ "defined": "7.18.13"
+ },
+ "stdc_has_single_bit_ui": {
+ "defined": "7.18.13"
+ },
+ "stdc_has_single_bit_ul": {
+ "defined": "7.18.13"
+ },
+ "stdc_has_single_bit_ull": {
+ "defined": "7.18.13"
+ },
+ "stdc_bit_width_uc": {
+ "defined": "7.18.14"
+ },
+ "stdc_bit_width_us": {
+ "defined": "7.18.14"
+ },
+ "stdc_bit_width_ui": {
+ "defined": "7.18.14"
+ },
+ "stdc_bit_width_ul": {
+ "defined": "7.18.14"
+ },
+ "stdc_bit_width_ull": {
+ "defined": "7.18.14"
+ },
+ "stdc_bit_floor_uc": {
+ "defined": "7.18.15"
+ },
+ "stdc_bit_floor_us": {
+ "defined": "7.18.15"
+ },
+ "stdc_bit_floor_ui": {
+ "defined": "7.18.15"
+ },
+ "stdc_bit_floor_ul": {
+ "defined": "7.18.15"
+ },
+ "stdc_bit_floor_ull": {
+ "defined": "7.18.15"
+ },
+ "stdc_bit_ceil_uc": {
+ "defined": "7.18.16"
+ },
+ "stdc_bit_ceil_us": {
+ "defined": "7.18.16"
+ },
+ "stdc_bit_ceil_ui": {
+ "defined": "7.18.16"
+ },
+ "stdc_bit_ceil_ul": {
+ "defined": "7.18.16"
+ },
+ "stdc_bit_ceil_ull": {
+ "defined": "7.18.16"
+ }
+ }
+}
More information about the libc-commits
mailing list