[libc-commits] [libc] [libc][docs] use docgen to generate stdbit rst docs (PR #88540)

via libc-commits libc-commits at lists.llvm.org
Fri Apr 12 10:27:57 PDT 2024


llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-libc

Author: Michael Flanders (Flandini)

<details>
<summary>Changes</summary>

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.

---
Full diff: https://github.com/llvm/llvm-project/pull/88540.diff


3 Files Affected:

- (modified) libc/docs/stdbit.rst (+219-131) 
- (modified) libc/utils/docgen/docgen.py (+8) 
- (added) libc/utils/docgen/stdbit.json (+234) 


``````````diff
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"
+    }
+  }
+}

``````````

</details>


https://github.com/llvm/llvm-project/pull/88540


More information about the libc-commits mailing list