Skip to content

Commit 2996cb7

Browse files
FlandiniFlandini
authored
[libc][docs] use docgen to generate stdbit rst docs (#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. Since macros aren't printed by docgen.py and are still a TODO in the code, they are also not printed in the new stdbit.h docs. 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.
1 parent 900be90 commit 2996cb7

File tree

3 files changed

+461
-131
lines changed

3 files changed

+461
-131
lines changed

‎libc/docs/stdbit.rst

Lines changed: 219 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,135 +1,223 @@
1-
=========================
2-
Bitwise Utility Functions
3-
=========================
4-
51
.. include:: check.rst
62

7-
---------------
8-
Source Location
9-
---------------
10-
11-
- The main source for bitwise utility functions is located at:
12-
``libc/src/stdbit``.
13-
14-
- The source for internal helpers used to implement these is located at:
15-
``libc/src/__support/CPP/bit.h``.
16-
17-
- The tests are located at:
18-
``libc/test/src/stdbit/``, ``libc/test/include/stdbit_test.cpp``, and
19-
``src/__support/CPP/bit_test.cpp``.
20-
21-
---------------------
22-
Implementation Status
23-
---------------------
24-
25-
Functions
26-
=========
27-
28-
..
29-
Do not order these, they are as they appear in the standard.
30-
31-
============================ =========
32-
Function Name Available
33-
============================ =========
34-
stdc_leading_zeros_uc |check|
35-
stdc_leading_zeros_us |check|
36-
stdc_leading_zeros_ui |check|
37-
stdc_leading_zeros_ul |check|
38-
stdc_leading_zeros_ull |check|
39-
stdc_leading_ones_uc |check|
40-
stdc_leading_ones_us |check|
41-
stdc_leading_ones_ui |check|
42-
stdc_leading_ones_ul |check|
43-
stdc_leading_ones_ull |check|
44-
stdc_trailing_zeros_uc |check|
45-
stdc_trailing_zeros_us |check|
46-
stdc_trailing_zeros_ui |check|
47-
stdc_trailing_zeros_ul |check|
48-
stdc_trailing_zeros_ull |check|
49-
stdc_trailing_ones_uc |check|
50-
stdc_trailing_ones_us |check|
51-
stdc_trailing_ones_ui |check|
52-
stdc_trailing_ones_ul |check|
53-
stdc_trailing_ones_ull |check|
54-
stdc_first_leading_zero_uc |check|
55-
stdc_first_leading_zero_us |check|
56-
stdc_first_leading_zero_ui |check|
57-
stdc_first_leading_zero_ul |check|
58-
stdc_first_leading_zero_ull |check|
59-
stdc_first_leading_one_uc |check|
60-
stdc_first_leading_one_us |check|
61-
stdc_first_leading_one_ui |check|
62-
stdc_first_leading_one_ul |check|
63-
stdc_first_leading_one_ull |check|
64-
stdc_first_trailing_zero_uc |check|
65-
stdc_first_trailing_zero_us |check|
66-
stdc_first_trailing_zero_ui |check|
67-
stdc_first_trailing_zero_ul |check|
68-
stdc_first_trailing_zero_ull |check|
69-
stdc_first_trailing_one_uc |check|
70-
stdc_first_trailing_one_us |check|
71-
stdc_first_trailing_one_ui |check|
72-
stdc_first_trailing_one_ul |check|
73-
stdc_first_trailing_one_ull |check|
74-
stdc_count_zeros_uc |check|
75-
stdc_count_zeros_us |check|
76-
stdc_count_zeros_ui |check|
77-
stdc_count_zeros_ul |check|
78-
stdc_count_zeros_ull |check|
79-
stdc_count_ones_uc |check|
80-
stdc_count_ones_us |check|
81-
stdc_count_ones_ui |check|
82-
stdc_count_ones_ul |check|
83-
stdc_count_ones_ull |check|
84-
stdc_has_single_bit_uc |check|
85-
stdc_has_single_bit_us |check|
86-
stdc_has_single_bit_ui |check|
87-
stdc_has_single_bit_ul |check|
88-
stdc_has_single_bit_ull |check|
89-
stdc_bit_width_uc |check|
90-
stdc_bit_width_us |check|
91-
stdc_bit_width_ui |check|
92-
stdc_bit_width_ul |check|
93-
stdc_bit_width_ull |check|
94-
stdc_bit_floor_uc |check|
95-
stdc_bit_floor_us |check|
96-
stdc_bit_floor_ui |check|
97-
stdc_bit_floor_ul |check|
98-
stdc_bit_floor_ull |check|
99-
stdc_bit_ceil_uc |check|
100-
stdc_bit_ceil_us |check|
101-
stdc_bit_ceil_ui |check|
102-
stdc_bit_ceil_ul |check|
103-
stdc_bit_ceil_ull |check|
104-
============================ =========
105-
106-
107-
Macros
108-
======
3+
stdbit.h Functions
4+
==================
1095

110-
========================= =========
111-
Macro Name Available
112-
========================= =========
113-
__STDC_VERSION_STDBIT_H__ |check|
114-
__STDC_ENDIAN_LITTLE__ |check|
115-
__STDC_ENDIAN_BIG__ |check|
116-
__STDC_ENDIAN_NATIVE__ |check|
117-
stdc_leading_zeros |check|
118-
stdc_leading_ones |check|
119-
stdc_trailing_zeros |check|
120-
stdc_trailing_ones |check|
121-
stdc_first_leading_zero |check|
122-
stdc_first_leading_one |check|
123-
stdc_first_trailing_zero |check|
124-
stdc_first_trailing_one |check|
125-
stdc_count_zeros |check|
126-
stdc_count_ones |check|
127-
stdc_has_single_bit |check|
128-
stdc_bit_width |check|
129-
stdc_bit_floor |check|
130-
stdc_bit_ceil |check|
131-
========================= =========
6+
.. list-table::
7+
:widths: auto
8+
:align: center
9+
:header-rows: 1
13210

133-
Standards
134-
=========
135-
stdbit.h was specified as part of C23 in section 7.18 "Bit and byte utilities."
11+
* - Function
12+
- Implemented
13+
- Standard
14+
* - stdc_bit_ceil_uc
15+
- |check|
16+
- 7.18.16
17+
* - stdc_bit_ceil_ui
18+
- |check|
19+
- 7.18.16
20+
* - stdc_bit_ceil_ul
21+
- |check|
22+
- 7.18.16
23+
* - stdc_bit_ceil_ull
24+
- |check|
25+
- 7.18.16
26+
* - stdc_bit_ceil_us
27+
- |check|
28+
- 7.18.16
29+
* - stdc_bit_floor_uc
30+
- |check|
31+
- 7.18.15
32+
* - stdc_bit_floor_ui
33+
- |check|
34+
- 7.18.15
35+
* - stdc_bit_floor_ul
36+
- |check|
37+
- 7.18.15
38+
* - stdc_bit_floor_ull
39+
- |check|
40+
- 7.18.15
41+
* - stdc_bit_floor_us
42+
- |check|
43+
- 7.18.15
44+
* - stdc_bit_width_uc
45+
- |check|
46+
- 7.18.14
47+
* - stdc_bit_width_ui
48+
- |check|
49+
- 7.18.14
50+
* - stdc_bit_width_ul
51+
- |check|
52+
- 7.18.14
53+
* - stdc_bit_width_ull
54+
- |check|
55+
- 7.18.14
56+
* - stdc_bit_width_us
57+
- |check|
58+
- 7.18.14
59+
* - stdc_count_ones_uc
60+
- |check|
61+
- 7.18.12
62+
* - stdc_count_ones_ui
63+
- |check|
64+
- 7.18.12
65+
* - stdc_count_ones_ul
66+
- |check|
67+
- 7.18.12
68+
* - stdc_count_ones_ull
69+
- |check|
70+
- 7.18.12
71+
* - stdc_count_ones_us
72+
- |check|
73+
- 7.18.12
74+
* - stdc_count_zeros_uc
75+
- |check|
76+
- 7.18.11
77+
* - stdc_count_zeros_ui
78+
- |check|
79+
- 7.18.11
80+
* - stdc_count_zeros_ul
81+
- |check|
82+
- 7.18.11
83+
* - stdc_count_zeros_ull
84+
- |check|
85+
- 7.18.11
86+
* - stdc_count_zeros_us
87+
- |check|
88+
- 7.18.11
89+
* - stdc_first_leading_one_uc
90+
- |check|
91+
- 7.18.8
92+
* - stdc_first_leading_one_ui
93+
- |check|
94+
- 7.18.8
95+
* - stdc_first_leading_one_ul
96+
- |check|
97+
- 7.18.8
98+
* - stdc_first_leading_one_ull
99+
- |check|
100+
- 7.18.8
101+
* - stdc_first_leading_one_us
102+
- |check|
103+
- 7.18.8
104+
* - stdc_first_leading_zero_uc
105+
- |check|
106+
- 7.18.7
107+
* - stdc_first_leading_zero_ui
108+
- |check|
109+
- 7.18.7
110+
* - stdc_first_leading_zero_ul
111+
- |check|
112+
- 7.18.7
113+
* - stdc_first_leading_zero_ull
114+
- |check|
115+
- 7.18.7
116+
* - stdc_first_leading_zero_us
117+
- |check|
118+
- 7.18.7
119+
* - stdc_first_trailing_one_uc
120+
- |check|
121+
- 7.18.10
122+
* - stdc_first_trailing_one_ui
123+
- |check|
124+
- 7.18.10
125+
* - stdc_first_trailing_one_ul
126+
- |check|
127+
- 7.18.10
128+
* - stdc_first_trailing_one_ull
129+
- |check|
130+
- 7.18.10
131+
* - stdc_first_trailing_one_us
132+
- |check|
133+
- 7.18.10
134+
* - stdc_first_trailing_zero_uc
135+
- |check|
136+
- 7.18.9
137+
* - stdc_first_trailing_zero_ui
138+
- |check|
139+
- 7.18.9
140+
* - stdc_first_trailing_zero_ul
141+
- |check|
142+
- 7.18.9
143+
* - stdc_first_trailing_zero_ull
144+
- |check|
145+
- 7.18.9
146+
* - stdc_first_trailing_zero_us
147+
- |check|
148+
- 7.18.9
149+
* - stdc_has_single_bit_uc
150+
- |check|
151+
- 7.18.13
152+
* - stdc_has_single_bit_ui
153+
- |check|
154+
- 7.18.13
155+
* - stdc_has_single_bit_ul
156+
- |check|
157+
- 7.18.13
158+
* - stdc_has_single_bit_ull
159+
- |check|
160+
- 7.18.13
161+
* - stdc_has_single_bit_us
162+
- |check|
163+
- 7.18.13
164+
* - stdc_leading_ones_uc
165+
- |check|
166+
- 7.18.4
167+
* - stdc_leading_ones_ui
168+
- |check|
169+
- 7.18.4
170+
* - stdc_leading_ones_ul
171+
- |check|
172+
- 7.18.4
173+
* - stdc_leading_ones_ull
174+
- |check|
175+
- 7.18.4
176+
* - stdc_leading_ones_us
177+
- |check|
178+
- 7.18.4
179+
* - stdc_leading_zeros_uc
180+
- |check|
181+
- 7.18.3
182+
* - stdc_leading_zeros_ui
183+
- |check|
184+
- 7.18.3
185+
* - stdc_leading_zeros_ul
186+
- |check|
187+
- 7.18.3
188+
* - stdc_leading_zeros_ull
189+
- |check|
190+
- 7.18.3
191+
* - stdc_leading_zeros_us
192+
- |check|
193+
- 7.18.3
194+
* - stdc_trailing_ones_uc
195+
- |check|
196+
- 7.18.6
197+
* - stdc_trailing_ones_ui
198+
- |check|
199+
- 7.18.6
200+
* - stdc_trailing_ones_ul
201+
- |check|
202+
- 7.18.6
203+
* - stdc_trailing_ones_ull
204+
- |check|
205+
- 7.18.6
206+
* - stdc_trailing_ones_us
207+
- |check|
208+
- 7.18.6
209+
* - stdc_trailing_zeros_uc
210+
- |check|
211+
- 7.18.5
212+
* - stdc_trailing_zeros_ui
213+
- |check|
214+
- 7.18.5
215+
* - stdc_trailing_zeros_ul
216+
- |check|
217+
- 7.18.5
218+
* - stdc_trailing_zeros_ull
219+
- |check|
220+
- 7.18.5
221+
* - stdc_trailing_zeros_us
222+
- |check|
223+
- 7.18.5

‎libc/utils/docgen/docgen.py

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,13 @@ def is_implemented(hname: str, fname: str) -> bool:
2828
"src",
2929
hname.rstrip(".h")
3030
)
31+
32+
if not path.exists():
33+
raise FileNotFoundError(f"implementation dir does not exist: {path}")
34+
35+
if not path.is_dir():
36+
raise NotADirectoryError(f"implementation dir is not a dir: {path}")
37+
3138
# Recursively search for the target source file in the subdirectories under
3239
# libc/src/{hname}.
3340
for _ in path.glob("**/" + fname + ".cpp"):
@@ -53,6 +60,7 @@ def print_functions(header: str, functions: Dict):
5360

5461

5562
def print_header(header: str, api: Dict):
63+
print(".. include:: check.rst\n")
5664
fns = f"{header} Functions"
5765
print(fns)
5866
print("=" * (len(fns)))

0 commit comments

Comments
 (0)