[libc-commits] [libc] [libc][docs] adds macro handling, POSIX status, and validation to docgen (PR #89421)
Michael Flanders via libc-commits
libc-commits at lists.llvm.org
Mon Apr 22 16:43:22 PDT 2024
https://github.com/Flandini updated https://github.com/llvm/llvm-project/pull/89421
>From 6e5a1440166bb280f7465fbe57492d4ce6d62371 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Thu, 18 Apr 2024 11:26:11 -0700
Subject: [PATCH 1/9] [libc][docs] adds macro handling, POSIX status, and
validation to docgen
docgen now lists macro implementation status in the generated rst files.
Adds POSIX definition link property to docgen json API (`posix-definition`)
and changes the `defined` property of docgen json API to `c-definition`. Now
that docgen's api is getting more specified, adds validation checks to docgen
to start codifying the docgen api spec.
To make sure this all looks good, I've added POSIX definition links to signal.h
as a tester. I'll attach the generated html file below for folks to preview.
---
libc/docs/ctype.rst | 25 +++-
libc/docs/fenv.rst | 117 ++++++++++++++-
libc/docs/signal.rst | 170 +++++++++++++++++++++-
libc/docs/stdbit.rst | 166 ++++++++++++++++++++-
libc/docs/threads.rst | 57 +++++++-
libc/utils/docgen/ctype.json | 28 ++--
libc/utils/docgen/docgen.py | 257 +++++++++++++++++++++++++++------
libc/utils/docgen/fenv.json | 72 ++++-----
libc/utils/docgen/signal.json | 145 ++++++++++++++++---
libc/utils/docgen/stdbit.json | 176 +++++++++++-----------
libc/utils/docgen/threads.json | 54 +++----
11 files changed, 1023 insertions(+), 244 deletions(-)
diff --git a/libc/docs/ctype.rst b/libc/docs/ctype.rst
index 7d77dadccc9ba3..e87116f10bfbdf 100644
--- a/libc/docs/ctype.rst
+++ b/libc/docs/ctype.rst
@@ -1,7 +1,11 @@
.. include:: check.rst
-ctype.h Functions
-=================
+=======
+ctype.h
+=======
+
+Functions
+=========
.. list-table::
:widths: auto
@@ -10,46 +14,61 @@ ctype.h Functions
* - Function
- Implemented
- - Standard
+ - C Standard
+ - POSIX Standard
* - isalnum
- |check|
- 7.4.1.1
+ -
* - isalpha
- |check|
- 7.4.1.2
+ -
* - isblank
- |check|
- 7.4.1.3
+ -
* - iscntrl
- |check|
- 7.4.1.4
+ -
* - isdigit
- |check|
- 7.4.1.5
+ -
* - isgraph
- |check|
- 7.4.1.6
+ -
* - islower
- |check|
- 7.4.1.7
+ -
* - isprint
- |check|
- 7.4.1.8
+ -
* - ispunct
- |check|
- 7.4.1.9
+ -
* - isspace
- |check|
- 7.4.1.10
+ -
* - isupper
- |check|
- 7.4.1.11
+ -
* - isxdigit
- |check|
- 7.4.1.12
+ -
* - tolower
- |check|
- 7.4.2.1
+ -
* - toupper
- |check|
- 7.4.2.2
+ -
diff --git a/libc/docs/fenv.rst b/libc/docs/fenv.rst
index 1dee5515e1174b..22bef37d9c8440 100644
--- a/libc/docs/fenv.rst
+++ b/libc/docs/fenv.rst
@@ -1,7 +1,11 @@
.. include:: check.rst
-fenv.h Functions
-================
+======
+fenv.h
+======
+
+Macros
+======
.. list-table::
:widths: auto
@@ -10,55 +14,162 @@ fenv.h Functions
* - Function
- Implemented
- - Standard
+ - C Standard
+ - POSIX Standard
+ * - FE_ALL_EXCEPT
+ - |check|
+ - 7.6.12
+ -
+ * - FE_DEC_DOWNWARD
+ -
+ - 7.6.14
+ -
+ * - FE_DEC_TONEAREST
+ -
+ - 7.6.14
+ -
+ * - FE_DEC_TONEARESTFROMZERO
+ -
+ - 7.6.14
+ -
+ * - FE_DEC_TOWARDZERO
+ -
+ - 7.6.14
+ -
+ * - FE_DEC_UPWARD
+ -
+ - 7.6.14
+ -
+ * - FE_DFL_ENV
+ - |check|
+ - 7.6.17
+ -
+ * - FE_DFL_MODE
+ -
+ - 7.6.11
+ -
+ * - FE_DIVBYZERO
+ - |check|
+ - 7.6.9
+ -
+ * - FE_DOWNARD
+ -
+ - 7.6.13
+ -
+ * - FE_INEXACT
+ - |check|
+ - 7.6.9
+ -
+ * - FE_INVALID
+ - |check|
+ - 7.6.9
+ -
+ * - FE_OVERFLOW
+ - |check|
+ - 7.6.9
+ -
+ * - FE_TONEAREST
+ - |check|
+ - 7.6.13
+ -
+ * - FE_TONEARESTFROMZERO
+ -
+ - 7.6.13
+ -
+ * - FE_TOWARDZERO
+ - |check|
+ - 7.6.13
+ -
+ * - FE_UNDERFLOW
+ - |check|
+ - 7.6.9
+ -
+ * - FE_UPWARD
+ - |check|
+ - 7.6.13
+ -
+ * - __STDC_VERSION_FENV_H__
+ -
+ - 7.6.5
+ -
+
+Functions
+=========
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Function
+ - Implemented
+ - C Standard
+ - POSIX Standard
* - fe_dec_getround
-
- 7.6.5.3
+ -
* - fe_dec_setround
-
- 7.6.5.6
+ -
* - feclearexcept
- |check|
- 7.6.4.1
+ -
* - fegetenv
- |check|
- 7.6.6.1
+ -
* - fegetexceptflag
- |check|
- 7.6.4.2
+ -
* - fegetmode
-
- 7.6.5.1
+ -
* - fegetround
- |check|
- 7.6.5.2
+ -
* - feholdexcept
- |check|
- 7.6.6.2
+ -
* - feraiseexcept
- |check|
- 7.6.4.3
+ -
* - fesetenv
- |check|
- 7.6.6.3
+ -
* - fesetexcept
- |check|
- 7.6.4.4
+ -
* - fesetexceptflag
- |check|
- 7.6.4.5
+ -
* - fesetmode
-
- 7.6.5.4
+ -
* - fesetround
- |check|
- 7.6.5.5
+ -
* - fetestexcept
- |check|
- 7.6.4.7
+ -
* - fetestexceptflag
- |check|
- 7.6.4.6
+ -
* - feupdateenv
- |check|
- 7.6.6.4
+ -
diff --git a/libc/docs/signal.rst b/libc/docs/signal.rst
index 7903bb439cb337..15d0aaaae3400d 100644
--- a/libc/docs/signal.rst
+++ b/libc/docs/signal.rst
@@ -1,7 +1,160 @@
.. include:: check.rst
-signal.h Functions
-==================
+========
+signal.h
+========
+
+Macros
+======
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Function
+ - Implemented
+ - C Standard
+ - POSIX Standard
+ * - SIGABRT
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGALRM
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGBUS
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGCHLD
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGCONT
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGFPE
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGHUP
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGILL
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGINT
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGKILL
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGPIPE
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGPOLL
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGPROF
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGQUIT
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGRTMAX
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGRTMIN
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGSEGV
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGSTOP
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGSYS
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGTERM
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGTRAP
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGTSTP
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGTTIN
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGTTOU
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGURG
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGUSR1
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGUSR2
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGVTALRM
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGXCPU
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGXFSZ
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIG_DFL
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIG_ERR
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIG_HOLD
+ -
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIG_IGN
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+
+Functions
+=========
.. list-table::
:widths: auto
@@ -10,34 +163,45 @@ signal.h Functions
* - Function
- Implemented
- - Standard
+ - C Standard
+ - POSIX Standard
* - kill
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/kill.html
* - raise
- |check|
- 7.14.2.1
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/raise.html
* - sigaction
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaction.html
* - sigaddset
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaddset.html
* - sigaltstack
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaltstack.html
* - sigdelset
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigdelset.html
* - sigemptyset
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigemptyset.html
* - sigfillset
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigfillset.html
* - signal
- |check|
- 7.14.1.1
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/signal.html
* - sigprocmask
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigprocmask.html
diff --git a/libc/docs/stdbit.rst b/libc/docs/stdbit.rst
index 0a12b2b6d7b513..47c3a00e2ba6c8 100644
--- a/libc/docs/stdbit.rst
+++ b/libc/docs/stdbit.rst
@@ -1,7 +1,96 @@
.. include:: check.rst
-stdbit.h Functions
-==================
+========
+stdbit.h
+========
+
+Macros
+======
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Function
+ - Implemented
+ - C Standard
+ - POSIX Standard
+ * - __STDC_ENDIAN_BIG__
+ - |check|
+ - 7.18.2.2
+ -
+ * - __STDC_ENDIAN_LITTLE__
+ - |check|
+ - 7.18.2.2
+ -
+ * - __STDC_ENDIAN_NATIVE__
+ - |check|
+ - 7.18.2.2
+ -
+ * - __STDC_VERSION_STDBIT_H__
+ - |check|
+ - 7.18.1.2
+ -
+ * - stdc_bit_ceil
+ - |check|
+ - 7.18.16.1
+ -
+ * - stdc_bit_floor
+ - |check|
+ - 7.18.15.1
+ -
+ * - stdc_bit_width
+ - |check|
+ - 7.18.14.1
+ -
+ * - stdc_count_ones
+ - |check|
+ - 7.18.12.1
+ -
+ * - stdc_count_zeros
+ - |check|
+ - 7.18.11.1
+ -
+ * - stdc_first_leading_one
+ - |check|
+ - 7.18.8.1
+ -
+ * - stdc_first_leading_zero
+ - |check|
+ - 7.18.7.1
+ -
+ * - stdc_first_trailing_one
+ - |check|
+ - 7.18.10.1
+ -
+ * - stdc_first_trailing_zero
+ - |check|
+ - 7.18.9.1
+ -
+ * - stdc_has_single_bit
+ - |check|
+ - 7.18.13.1
+ -
+ * - stdc_leading_ones
+ - |check|
+ - 7.18.4.1
+ -
+ * - stdc_leading_zeros
+ - |check|
+ - 7.18.3.1
+ -
+ * - stdc_trailing_ones
+ - |check|
+ - 7.18.6.1
+ -
+ * - stdc_trailing_zeros
+ - |check|
+ - 7.18.5.1
+ -
+
+Functions
+=========
.. list-table::
:widths: auto
@@ -10,214 +99,285 @@ stdbit.h Functions
* - Function
- Implemented
- - Standard
+ - C Standard
+ - POSIX 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/docs/threads.rst b/libc/docs/threads.rst
index 78e17e9fdec3aa..360b29a64abd87 100644
--- a/libc/docs/threads.rst
+++ b/libc/docs/threads.rst
@@ -1,7 +1,32 @@
.. include:: check.rst
-threads.h Functions
-===================
+=========
+threads.h
+=========
+
+Macros
+======
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Function
+ - Implemented
+ - C Standard
+ - POSIX Standard
+ * - ONCE_FLAG_INIT
+ -
+ - 7.28.1.3
+ -
+ * - TSS_DTOR_ITERATIONS
+ -
+ - 7.28.1.3
+ -
+
+Functions
+=========
.. list-table::
:widths: auto
@@ -10,79 +35,105 @@ threads.h Functions
* - Function
- Implemented
- - Standard
+ - C Standard
+ - POSIX Standard
* - call_once
- |check|
- 7.28.2.1
+ -
* - cnd_broadcast
- |check|
- 7.28.3.1
+ -
* - cnd_destroy
- |check|
- 7.28.3.2
+ -
* - cnd_init
- |check|
- 7.28.3.3
+ -
* - cnd_signal
- |check|
- 7.28.3.4
+ -
* - cnd_timedwait
-
- 7.28.3.5
+ -
* - cnd_wait
- |check|
- 7.28.3.6
+ -
* - mtx_destroy
- |check|
- 7.28.4.1
+ -
* - mtx_init
- |check|
- 7.28.4.2
+ -
* - mtx_lock
- |check|
- 7.28.4.3
+ -
* - mtx_timedlock
-
- 7.28.4.4
+ -
* - mtx_trylock
-
- 7.28.4.5
+ -
* - mtx_unlock
- |check|
- 7.28.4.6
+ -
* - thrd_create
- |check|
- 7.28.5.1
+ -
* - thrd_current
- |check|
- 7.28.5.2
+ -
* - thrd_detach
- |check|
- 7.28.5.3
+ -
* - thrd_equal
- |check|
- 7.28.5.4
+ -
* - thrd_exit
- |check|
- 7.28.5.5
+ -
* - thrd_join
- |check|
- 7.28.5.6
+ -
* - thrd_sleep
-
- 7.28.5.7
+ -
* - thrd_yield
-
- 7.28.5.8
+ -
* - tss_create
- |check|
- 7.28.6.1
+ -
* - tss_delete
- |check|
- 7.28.6.2
+ -
* - tss_get
- |check|
- 7.28.6.3
+ -
* - tss_set
- |check|
- 7.28.6.4
+ -
diff --git a/libc/utils/docgen/ctype.json b/libc/utils/docgen/ctype.json
index 25eeb683846cfb..af97e4bbbc0a27 100644
--- a/libc/utils/docgen/ctype.json
+++ b/libc/utils/docgen/ctype.json
@@ -1,46 +1,46 @@
{
"functions": {
"isalnum": {
- "defined": "7.4.1.1"
+ "c-definition": "7.4.1.1"
},
"isalpha": {
- "defined": "7.4.1.2"
+ "c-definition": "7.4.1.2"
},
"isblank": {
- "defined": "7.4.1.3"
+ "c-definition": "7.4.1.3"
},
"iscntrl": {
- "defined": "7.4.1.4"
+ "c-definition": "7.4.1.4"
},
"isdigit": {
- "defined": "7.4.1.5"
+ "c-definition": "7.4.1.5"
},
"isgraph": {
- "defined": "7.4.1.6"
+ "c-definition": "7.4.1.6"
},
"islower": {
- "defined": "7.4.1.7"
+ "c-definition": "7.4.1.7"
},
"isprint": {
- "defined": "7.4.1.8"
+ "c-definition": "7.4.1.8"
},
"ispunct": {
- "defined": "7.4.1.9"
+ "c-definition": "7.4.1.9"
},
"isspace": {
- "defined": "7.4.1.10"
+ "c-definition": "7.4.1.10"
},
"isupper": {
- "defined": "7.4.1.11"
+ "c-definition": "7.4.1.11"
},
"isxdigit": {
- "defined": "7.4.1.12"
+ "c-definition": "7.4.1.12"
},
"tolower" : {
- "defined": "7.4.2.1"
+ "c-definition": "7.4.2.1"
},
"toupper": {
- "defined": "7.4.2.2"
+ "c-definition": "7.4.2.2"
}
}
}
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 23d45305fe513c..43fa6c8e3dfcf2 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -9,61 +9,160 @@
# ==-------------------------------------------------------------------------==#
from argparse import ArgumentParser, Namespace
from pathlib import Path
-from typing import Dict
+from typing import Dict, Generator
import sys
import json
-def load_api(hname: str) -> Dict:
- p = Path(__file__).parent / Path(hname).with_suffix(".json")
- api = p.read_text(encoding="utf-8")
- return json.loads(api)
+class DocgenAPIFormatError(Exception):
+ """Raised on fatal formatting errors with a description of a formatting error"""
-# TODO: we may need to get more sophisticated for less generic implementations.
-# Does libc/src/{hname minus .h suffix}/{fname}.cpp exist?
-def is_implemented(hname: str, fname: str) -> bool:
- path = Path(
- Path(__file__).parent.parent.parent,
- "src",
- hname.rstrip(".h")
- )
+class Header:
+ """
+ Maintains implementation information about a standard header file:
+ * where does its implementation dir live
+ * where is its macros file
+ * where is its docgen json file
- if not path.exists():
- raise FileNotFoundError(f"implementation dir does not exist: {path}")
+ By convention, the macro-only part of a header file is in a header-specific
+ file somewhere in the directory tree with root at
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros``. Docgen expects that
+ if a macro is implemented, that it appears in a string
+ ``#define MACRO_NAME`` in some ``*-macros.h`` file in the directory tree..
+ Docgen searches for this string in the file to set the implementation status
+ shown in the generated rst docs rendered as html for display at
+ <libc.llvm.org>.
- if not path.is_dir():
- raise NotADirectoryError(f"implementation dir is not a dir: {path}")
+ By convention, each function for a header is implemented in a function-specific
+ cpp file somewhere in the directory tree with root at, e.g,
+ ``$LLVM_PROJECT_ROOT/libc/src/fenv``. Some headers have architecture-specific
+ implementations, like ``math``, and some don't, like ``fenv``. Docgen uses the
+ presence of this function-specific cpp file to set the implementation status
+ shown in the generated rst docs rendered as html for display at
+ <libc.llvm.org>.
+ """
- # Recursively search for the target source file in the subdirectories under
- # libc/src/{hname}.
- for _ in path.glob("**/" + fname + ".cpp"):
- return True
+ def __init__(self, header_name: str):
+ """
+ :param header_name: e.g., ``"threads.h"`` or ``"signal.h"``
+ """
+ self.name = header_name
+ self.stem = header_name.rstrip(".h")
+ self.libc_root = Path(__file__).parent.parent.parent
+ self.docgen_root = Path(__file__).parent
+ self.docgen_json = self.docgen_root / Path(header_name).with_suffix(".json")
+ self.fns_dir = Path(self.libc_root, "src", self.stem)
+ self.macros_dir = Path(self.libc_root, "include", "llvm-libc-macros")
- return False
+ def macro_file_exists(self) -> bool:
+ for _ in self.__get_macro_files():
+ return True
+ return False
-def print_functions(header: str, functions: Dict):
- for key in sorted(functions.keys()):
- print(f" * - {key}")
+ def fns_dir_exists(self) -> bool:
+ return self.fns_dir.exists() and self.fns_dir.is_dir()
- if is_implemented(header, key):
- print(" - |check|")
- else:
- print(" -")
+ def implements_fn(self, fn_name: str) -> bool:
+ for _ in self.fns_dir.glob(f"**/{fn_name}.cpp"):
+ return True
- # defined is optional. Having any content is optional.
- if functions[key] is not None and "defined" in functions[key]:
- print(f' - {functions[key]["defined"]}')
- else:
- print(" -")
+ return False
+ def implements_macro(self, m_name: str) -> bool:
+ """
+ Some macro files are in, e.g.,
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/fenv-macros.h``,
+ but others are in subdirectories, e.g., ``signal.h`` has the macro
+ definitions in
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/linux/signal-macros.h``.
-def print_header(header: str, api: Dict):
- print(".. include:: check.rst\n")
- fns = f"{header} Functions"
- print(fns)
- print("=" * (len(fns)))
+ :param m_name: name of macro, e.g., ``FE_ALL_EXCEPT``
+ """
+ for f in self.__get_macro_files():
+ if f"#define {m_name}" in f.read_text():
+ return True
+
+ return False
+
+ def __get_macro_files(self) -> Generator[Path, None, None]:
+ return self.macros_dir.glob(f"**/{self.stem}-macros.h")
+
+
+def check_api(header: Header, api: Dict):
+ """
+ Checks that docgen json files are properly formatted. If there are any
+ fatal formatting errors, raises exceptions with error messages useful for
+ fixing formatting. Warnings are printed to stderr on non-fatal formatting
+ errors. The code that runs after ``check_api(api)`` is called expects that
+ ``check_api`` executed without raising formatting exceptions so the json
+ matches the formatting specified here.
+
+ The json file may contain:
+ * an optional macros object
+ * an optional functions object
+
+ Formatting of ``macros`` and ``functions`` objects
+ ==================================================
+
+ If a macros or functions object is present, then it may contain nested
+ objects. Each of these nested objects should have a name matching a macro
+ or function's name, and each nested object must have the property:
+ ``"c-definition"`` or ``"posix-definition"``.
+
+ Description of properties
+ =========================
+ The defined property is intended to be a reference to a part of the
+ standard that defines the function or macro. For the ``"c-definition"`` property,
+ this should be a C standard section number. For the ``"posix-definition"`` property,
+ this should be a link to the definition.
+
+ :param api: docgen json file contents parsed into a dict
+ """
+ errors = []
+ cdef = "c-definition"
+ pdef = "posix-definition"
+
+ # Validate macros
+ if "macros" in api:
+ if not header.macro_file_exists():
+ print(
+ f"warning: Macro definitions are listed for {header.name}, but no macro file can be found in the directory tree rooted at {header.macros_dir}. All macros will be listed as not implemented.",
+ file=sys.stderr,
+ )
+
+ macros = api["macros"]
+
+ for name, obj in macros.items():
+ if not (cdef in obj or pdef in obj):
+ err = f'error: Macro {name} does not contain at least one required property: "{cdef}" or "{pdef}"'
+ errors.append(err)
+
+ # Validate functions
+ if "functions" in api:
+ if not header.fns_dir_exists():
+ print(
+ f"warning: Function definitions are listed for {header.name}, but no function implementation directory exists at {header.fns_dir}. All functions will be listed as not implemented.",
+ file=sys.stderr,
+ )
+
+ fns = api["functions"]
+ for name, obj in fns.items():
+ if not (cdef in obj or pdef in obj):
+ err = f'error: function {name} does not contain at least one required property: "{cdef}" or "{pdef}"'
+ errors.append(err)
+
+ if errors:
+ raise DocgenAPIFormatError("\n".join(errors))
+
+
+def load_api(header: Header) -> Dict:
+ api = header.docgen_json.read_text(encoding="utf-8")
+ return json.loads(api)
+
+
+def print_tbl_dir():
print(
f"""
.. list-table::
@@ -73,10 +172,78 @@ def print_header(header: str, api: Dict):
* - Function
- Implemented
- - Standard"""
+ - C Standard
+ - POSIX Standard"""
)
- # TODO: how do we want to signal implementation of macros?
- print_functions(header, api["functions"])
+
+
+def print_functions_rst(header: Header, functions: Dict):
+ tbl_hdr = "Functions"
+ print(tbl_hdr)
+ print("=" * len(tbl_hdr))
+
+ print_tbl_dir()
+
+ for name in sorted(functions.keys()):
+ print(f" * - {name}")
+
+ if header.fns_dir_exists() and header.implements_fn(name):
+ print(" - |check|")
+ else:
+ print(" -")
+
+ if "c-definition" in functions[name]:
+ print(f' - {functions[name]["c-definition"]}')
+ else:
+ print(" -")
+
+ if "posix-definition" in functions[name]:
+ print(f' - {functions[name]["posix-definition"]}')
+ else:
+ print(" -")
+
+
+def print_macros_rst(header: Header, macros: Dict):
+ tbl_hdr = "Macros"
+ print(tbl_hdr)
+ print("=" * len(tbl_hdr))
+
+ print_tbl_dir()
+
+ for name in sorted(macros.keys()):
+ print(f" * - {name}")
+
+ if header.macro_file_exists() and header.implements_macro(name):
+ print(" - |check|")
+ else:
+ print(" -")
+
+ if "c-definition" in macros[name]:
+ print(f' - {macros[name]["c-definition"]}')
+ else:
+ print(" -")
+
+ if "posix-definition" in macros[name]:
+ print(f' - {macros[name]["posix-definition"]}')
+ else:
+ print(" -")
+
+
+def print_impl_status_rst(header: Header, api: Dict):
+ print(".. include:: check.rst\n")
+
+ print("=" * len(header.name))
+ print(header.name)
+ print("=" * len(header.name))
+ print()
+
+ # the macro and function sections are both optional
+ if "macros" in api:
+ print_macros_rst(header, api["macros"])
+ print()
+
+ if "functions" in api:
+ print_functions_rst(header, api["functions"])
def parse_args() -> Namespace:
@@ -88,6 +255,8 @@ def parse_args() -> Namespace:
if __name__ == "__main__":
args = parse_args()
- api = load_api(args.header_name)
+ header = Header(args.header_name)
+ api = load_api(header)
+ check_api(header, api)
- print_header(args.header_name, api)
+ print_impl_status_rst(header, api)
diff --git a/libc/utils/docgen/fenv.json b/libc/utils/docgen/fenv.json
index 9aa3f641ddc94b..788b196c053bcc 100644
--- a/libc/utils/docgen/fenv.json
+++ b/libc/utils/docgen/fenv.json
@@ -1,114 +1,114 @@
{
"macros": {
"__STDC_VERSION_FENV_H__": {
- "defined": "7.6.5"
+ "c-definition": "7.6.5"
},
"FE_DIVBYZERO": {
- "defined": "7.6.9"
+ "c-definition": "7.6.9"
},
"FE_INEXACT": {
- "defined": "7.6.9"
+ "c-definition": "7.6.9"
},
"FE_INVALID": {
- "defined": "7.6.9"
+ "c-definition": "7.6.9"
},
"FE_OVERFLOW": {
- "defined": "7.6.9"
+ "c-definition": "7.6.9"
},
"FE_UNDERFLOW": {
- "defined": "7.6.9"
+ "c-definition": "7.6.9"
},
"FE_ALL_EXCEPT": {
- "defined": "7.6.12"
+ "c-definition": "7.6.12"
},
"FE_DFL_MODE": {
- "defined": "7.6.11"
+ "c-definition": "7.6.11"
},
"FE_DOWNARD": {
- "defined": "7.6.13"
+ "c-definition": "7.6.13"
},
"FE_TONEAREST": {
- "defined": "7.6.13"
+ "c-definition": "7.6.13"
},
"FE_TONEARESTFROMZERO": {
- "defined": "7.6.13"
+ "c-definition": "7.6.13"
},
"FE_TOWARDZERO": {
- "defined": "7.6.13"
+ "c-definition": "7.6.13"
},
"FE_UPWARD": {
- "defined": "7.6.13"
+ "c-definition": "7.6.13"
},
"FE_DEC_DOWNWARD": {
- "defined": "7.6.14"
+ "c-definition": "7.6.14"
},
"FE_DEC_TONEAREST": {
- "defined": "7.6.14"
+ "c-definition": "7.6.14"
},
"FE_DEC_TONEARESTFROMZERO": {
- "defined": "7.6.14"
+ "c-definition": "7.6.14"
},
"FE_DEC_TOWARDZERO": {
- "defined": "7.6.14"
+ "c-definition": "7.6.14"
},
"FE_DEC_UPWARD": {
- "defined": "7.6.14"
+ "c-definition": "7.6.14"
},
"FE_DFL_ENV": {
- "defined": "7.6.17"
+ "c-definition": "7.6.17"
}
},
"functions": {
"feclearexcept": {
- "defined": "7.6.4.1"
+ "c-definition": "7.6.4.1"
},
"fegetexceptflag": {
- "defined": "7.6.4.2"
+ "c-definition": "7.6.4.2"
},
"feraiseexcept": {
- "defined": "7.6.4.3"
+ "c-definition": "7.6.4.3"
},
"fesetexcept": {
- "defined": "7.6.4.4"
+ "c-definition": "7.6.4.4"
},
"fesetexceptflag": {
- "defined": "7.6.4.5"
+ "c-definition": "7.6.4.5"
},
"fetestexceptflag": {
- "defined": "7.6.4.6"
+ "c-definition": "7.6.4.6"
},
"fetestexcept": {
- "defined": "7.6.4.7"
+ "c-definition": "7.6.4.7"
},
"fegetmode": {
- "defined": "7.6.5.1"
+ "c-definition": "7.6.5.1"
},
"fegetround": {
- "defined": "7.6.5.2"
+ "c-definition": "7.6.5.2"
},
"fe_dec_getround": {
- "defined": "7.6.5.3"
+ "c-definition": "7.6.5.3"
},
"fesetmode": {
- "defined": "7.6.5.4"
+ "c-definition": "7.6.5.4"
},
"fesetround": {
- "defined": "7.6.5.5"
+ "c-definition": "7.6.5.5"
},
"fe_dec_setround": {
- "defined": "7.6.5.6"
+ "c-definition": "7.6.5.6"
},
"fegetenv": {
- "defined": "7.6.6.1"
+ "c-definition": "7.6.6.1"
},
"feholdexcept": {
- "defined": "7.6.6.2"
+ "c-definition": "7.6.6.2"
},
"fesetenv": {
- "defined": "7.6.6.3"
+ "c-definition": "7.6.6.3"
},
"feupdateenv": {
- "defined": "7.6.6.4"
+ "c-definition": "7.6.6.4"
}
}
}
diff --git a/libc/utils/docgen/signal.json b/libc/utils/docgen/signal.json
index d5380d348b7d66..337b0c19717b71 100644
--- a/libc/utils/docgen/signal.json
+++ b/libc/utils/docgen/signal.json
@@ -1,47 +1,152 @@
{
"macros": {
"SIG_DFL": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIG_ERR": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIG_HOLD": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIG_IGN": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGRTMIN": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGRTMAX": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGABRT": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGALRM": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGBUS": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGCHLD": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGCONT": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGFPE": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGHUP": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGILL": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGINT": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGKILL": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGPIPE": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGPIPE": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGQUIT": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGSEGV": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGSTOP": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGTERM": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGTSTP": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGTTIN": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGTTOU": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGUSR1": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGUSR2": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGPOLL": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGPROF": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGSYS": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGTRAP": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGURG": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGVTALRM": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGXCPU": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGXFSZ": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
}
},
"functions": {
"signal": {
- "defined": "7.14.1.1"
+ "c-definition": "7.14.1.1",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/signal.html"
},
"raise": {
- "defined": "7.14.2.1"
- },
- "kill": null,
- "sigaction": null,
- "sigaddset": null,
- "sigaltstack": null,
- "sigdelset": null,
- "sigemptyset": null,
- "sigfillset": null,
- "sigprocmask": null
+ "c-definition": "7.14.2.1",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/raise.html"
+ },
+ "kill": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/kill.html"
+ },
+ "sigaction": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaction.html"
+ },
+ "sigaddset": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaddset.html"
+ },
+ "sigaltstack": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaltstack.html"
+ },
+ "sigdelset": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigdelset.html"
+ },
+ "sigemptyset": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigemptyset.html"
+ },
+ "sigfillset": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigfillset.html"
+ },
+ "sigprocmask": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigprocmask.html"
+ }
}
}
diff --git a/libc/utils/docgen/stdbit.json b/libc/utils/docgen/stdbit.json
index 88106cf0e4f97b..25060c1ff9fd8b 100644
--- a/libc/utils/docgen/stdbit.json
+++ b/libc/utils/docgen/stdbit.json
@@ -1,270 +1,270 @@
{
"macros": {
"__STDC_VERSION_STDBIT_H__": {
- "defined": "7.18.1.2"
+ "c-definition": "7.18.1.2"
},
"__STDC_ENDIAN_LITTLE__": {
- "defined": "7.18.2.2"
+ "c-definition": "7.18.2.2"
},
"__STDC_ENDIAN_BIG__": {
- "defined": "7.18.2.2"
+ "c-definition": "7.18.2.2"
},
"__STDC_ENDIAN_NATIVE__": {
- "defined": "7.18.2.2"
+ "c-definition": "7.18.2.2"
},
"stdc_leading_zeros": {
- "defined": "7.18.3.1"
+ "c-definition": "7.18.3.1"
},
"stdc_leading_ones": {
- "defined": "7.18.4.1"
+ "c-definition": "7.18.4.1"
},
"stdc_trailing_zeros": {
- "defined": "7.18.5.1"
+ "c-definition": "7.18.5.1"
},
"stdc_trailing_ones": {
- "defined": "7.18.6.1"
+ "c-definition": "7.18.6.1"
},
"stdc_first_leading_zero": {
- "defined": "7.18.7.1"
+ "c-definition": "7.18.7.1"
},
"stdc_first_leading_one": {
- "defined": "7.18.8.1"
+ "c-definition": "7.18.8.1"
},
"stdc_first_trailing_zero": {
- "defined": "7.18.9.1"
+ "c-definition": "7.18.9.1"
},
"stdc_first_trailing_one": {
- "defined": "7.18.10.1"
+ "c-definition": "7.18.10.1"
},
"stdc_count_zeros": {
- "defined": "7.18.11.1"
+ "c-definition": "7.18.11.1"
},
"stdc_count_ones": {
- "defined": "7.18.12.1"
+ "c-definition": "7.18.12.1"
},
"stdc_has_single_bit": {
- "defined": "7.18.13.1"
+ "c-definition": "7.18.13.1"
},
"stdc_bit_width": {
- "defined": "7.18.14.1"
+ "c-definition": "7.18.14.1"
},
"stdc_bit_floor": {
- "defined": "7.18.15.1"
+ "c-definition": "7.18.15.1"
},
"stdc_bit_ceil": {
- "defined": "7.18.16.1"
+ "c-definition": "7.18.16.1"
}
},
"functions": {
"stdc_leading_zeros_uc": {
- "defined": "7.18.3"
+ "c-definition": "7.18.3"
},
"stdc_leading_zeros_us": {
- "defined": "7.18.3"
+ "c-definition": "7.18.3"
},
"stdc_leading_zeros_ui": {
- "defined": "7.18.3"
+ "c-definition": "7.18.3"
},
"stdc_leading_zeros_ul": {
- "defined": "7.18.3"
+ "c-definition": "7.18.3"
},
"stdc_leading_zeros_ull": {
- "defined": "7.18.3"
+ "c-definition": "7.18.3"
},
"stdc_leading_ones_uc": {
- "defined": "7.18.4"
+ "c-definition": "7.18.4"
},
"stdc_leading_ones_us": {
- "defined": "7.18.4"
+ "c-definition": "7.18.4"
},
"stdc_leading_ones_ui": {
- "defined": "7.18.4"
+ "c-definition": "7.18.4"
},
"stdc_leading_ones_ul": {
- "defined": "7.18.4"
+ "c-definition": "7.18.4"
},
"stdc_leading_ones_ull": {
- "defined": "7.18.4"
+ "c-definition": "7.18.4"
},
"stdc_trailing_zeros_uc": {
- "defined": "7.18.5"
+ "c-definition": "7.18.5"
},
"stdc_trailing_zeros_us": {
- "defined": "7.18.5"
+ "c-definition": "7.18.5"
},
"stdc_trailing_zeros_ui": {
- "defined": "7.18.5"
+ "c-definition": "7.18.5"
},
"stdc_trailing_zeros_ul": {
- "defined": "7.18.5"
+ "c-definition": "7.18.5"
},
"stdc_trailing_zeros_ull": {
- "defined": "7.18.5"
+ "c-definition": "7.18.5"
},
"stdc_trailing_ones_uc": {
- "defined": "7.18.6"
+ "c-definition": "7.18.6"
},
"stdc_trailing_ones_us": {
- "defined": "7.18.6"
+ "c-definition": "7.18.6"
},
"stdc_trailing_ones_ui": {
- "defined": "7.18.6"
+ "c-definition": "7.18.6"
},
"stdc_trailing_ones_ul": {
- "defined": "7.18.6"
+ "c-definition": "7.18.6"
},
"stdc_trailing_ones_ull": {
- "defined": "7.18.6"
+ "c-definition": "7.18.6"
},
"stdc_first_leading_zero_uc": {
- "defined": "7.18.7"
+ "c-definition": "7.18.7"
},
"stdc_first_leading_zero_us": {
- "defined": "7.18.7"
+ "c-definition": "7.18.7"
},
"stdc_first_leading_zero_ui": {
- "defined": "7.18.7"
+ "c-definition": "7.18.7"
},
"stdc_first_leading_zero_ul": {
- "defined": "7.18.7"
+ "c-definition": "7.18.7"
},
"stdc_first_leading_zero_ull": {
- "defined": "7.18.7"
+ "c-definition": "7.18.7"
},
"stdc_first_leading_one_uc": {
- "defined": "7.18.8"
+ "c-definition": "7.18.8"
},
"stdc_first_leading_one_us": {
- "defined": "7.18.8"
+ "c-definition": "7.18.8"
},
"stdc_first_leading_one_ui": {
- "defined": "7.18.8"
+ "c-definition": "7.18.8"
},
"stdc_first_leading_one_ul": {
- "defined": "7.18.8"
+ "c-definition": "7.18.8"
},
"stdc_first_leading_one_ull": {
- "defined": "7.18.8"
+ "c-definition": "7.18.8"
},
"stdc_first_trailing_zero_uc": {
- "defined": "7.18.9"
+ "c-definition": "7.18.9"
},
"stdc_first_trailing_zero_us": {
- "defined": "7.18.9"
+ "c-definition": "7.18.9"
},
"stdc_first_trailing_zero_ui": {
- "defined": "7.18.9"
+ "c-definition": "7.18.9"
},
"stdc_first_trailing_zero_ul": {
- "defined": "7.18.9"
+ "c-definition": "7.18.9"
},
"stdc_first_trailing_zero_ull": {
- "defined": "7.18.9"
+ "c-definition": "7.18.9"
},
"stdc_first_trailing_one_uc": {
- "defined": "7.18.10"
+ "c-definition": "7.18.10"
},
"stdc_first_trailing_one_us": {
- "defined": "7.18.10"
+ "c-definition": "7.18.10"
},
"stdc_first_trailing_one_ui": {
- "defined": "7.18.10"
+ "c-definition": "7.18.10"
},
"stdc_first_trailing_one_ul": {
- "defined": "7.18.10"
+ "c-definition": "7.18.10"
},
"stdc_first_trailing_one_ull": {
- "defined": "7.18.10"
+ "c-definition": "7.18.10"
},
"stdc_count_zeros_uc": {
- "defined": "7.18.11"
+ "c-definition": "7.18.11"
},
"stdc_count_zeros_us": {
- "defined": "7.18.11"
+ "c-definition": "7.18.11"
},
"stdc_count_zeros_ui": {
- "defined": "7.18.11"
+ "c-definition": "7.18.11"
},
"stdc_count_zeros_ul": {
- "defined": "7.18.11"
+ "c-definition": "7.18.11"
},
"stdc_count_zeros_ull": {
- "defined": "7.18.11"
+ "c-definition": "7.18.11"
},
"stdc_count_ones_uc": {
- "defined": "7.18.12"
+ "c-definition": "7.18.12"
},
"stdc_count_ones_us": {
- "defined": "7.18.12"
+ "c-definition": "7.18.12"
},
"stdc_count_ones_ui": {
- "defined": "7.18.12"
+ "c-definition": "7.18.12"
},
"stdc_count_ones_ul": {
- "defined": "7.18.12"
+ "c-definition": "7.18.12"
},
"stdc_count_ones_ull": {
- "defined": "7.18.12"
+ "c-definition": "7.18.12"
},
"stdc_has_single_bit_uc": {
- "defined": "7.18.13"
+ "c-definition": "7.18.13"
},
"stdc_has_single_bit_us": {
- "defined": "7.18.13"
+ "c-definition": "7.18.13"
},
"stdc_has_single_bit_ui": {
- "defined": "7.18.13"
+ "c-definition": "7.18.13"
},
"stdc_has_single_bit_ul": {
- "defined": "7.18.13"
+ "c-definition": "7.18.13"
},
"stdc_has_single_bit_ull": {
- "defined": "7.18.13"
+ "c-definition": "7.18.13"
},
"stdc_bit_width_uc": {
- "defined": "7.18.14"
+ "c-definition": "7.18.14"
},
"stdc_bit_width_us": {
- "defined": "7.18.14"
+ "c-definition": "7.18.14"
},
"stdc_bit_width_ui": {
- "defined": "7.18.14"
+ "c-definition": "7.18.14"
},
"stdc_bit_width_ul": {
- "defined": "7.18.14"
+ "c-definition": "7.18.14"
},
"stdc_bit_width_ull": {
- "defined": "7.18.14"
+ "c-definition": "7.18.14"
},
"stdc_bit_floor_uc": {
- "defined": "7.18.15"
+ "c-definition": "7.18.15"
},
"stdc_bit_floor_us": {
- "defined": "7.18.15"
+ "c-definition": "7.18.15"
},
"stdc_bit_floor_ui": {
- "defined": "7.18.15"
+ "c-definition": "7.18.15"
},
"stdc_bit_floor_ul": {
- "defined": "7.18.15"
+ "c-definition": "7.18.15"
},
"stdc_bit_floor_ull": {
- "defined": "7.18.15"
+ "c-definition": "7.18.15"
},
"stdc_bit_ceil_uc": {
- "defined": "7.18.16"
+ "c-definition": "7.18.16"
},
"stdc_bit_ceil_us": {
- "defined": "7.18.16"
+ "c-definition": "7.18.16"
},
"stdc_bit_ceil_ui": {
- "defined": "7.18.16"
+ "c-definition": "7.18.16"
},
"stdc_bit_ceil_ul": {
- "defined": "7.18.16"
+ "c-definition": "7.18.16"
},
"stdc_bit_ceil_ull": {
- "defined": "7.18.16"
+ "c-definition": "7.18.16"
}
}
}
diff --git a/libc/utils/docgen/threads.json b/libc/utils/docgen/threads.json
index aef6ffaf75bae3..8591cbde55a49a 100644
--- a/libc/utils/docgen/threads.json
+++ b/libc/utils/docgen/threads.json
@@ -1,87 +1,87 @@
{
"macros": {
"ONCE_FLAG_INIT": {
- "defined": "7.28.1.3"
+ "c-definition": "7.28.1.3"
},
"TSS_DTOR_ITERATIONS": {
- "defined": "7.28.1.3"
+ "c-definition": "7.28.1.3"
}
},
"functions": {
"call_once": {
- "defined": "7.28.2.1"
+ "c-definition": "7.28.2.1"
},
"cnd_broadcast": {
- "defined": "7.28.3.1"
+ "c-definition": "7.28.3.1"
},
"cnd_destroy": {
- "defined": "7.28.3.2"
+ "c-definition": "7.28.3.2"
},
"cnd_init": {
- "defined": "7.28.3.3"
+ "c-definition": "7.28.3.3"
},
"cnd_signal": {
- "defined": "7.28.3.4"
+ "c-definition": "7.28.3.4"
},
"cnd_timedwait": {
- "defined": "7.28.3.5"
+ "c-definition": "7.28.3.5"
},
"cnd_wait": {
- "defined": "7.28.3.6"
+ "c-definition": "7.28.3.6"
},
"mtx_destroy": {
- "defined": "7.28.4.1"
+ "c-definition": "7.28.4.1"
},
"mtx_init": {
- "defined": "7.28.4.2"
+ "c-definition": "7.28.4.2"
},
"mtx_lock": {
- "defined": "7.28.4.3"
+ "c-definition": "7.28.4.3"
},
"mtx_timedlock": {
- "defined": "7.28.4.4"
+ "c-definition": "7.28.4.4"
},
"mtx_trylock": {
- "defined": "7.28.4.5"
+ "c-definition": "7.28.4.5"
},
"mtx_unlock": {
- "defined": "7.28.4.6"
+ "c-definition": "7.28.4.6"
},
"thrd_create": {
- "defined": "7.28.5.1"
+ "c-definition": "7.28.5.1"
},
"thrd_current": {
- "defined": "7.28.5.2"
+ "c-definition": "7.28.5.2"
},
"thrd_detach": {
- "defined": "7.28.5.3"
+ "c-definition": "7.28.5.3"
},
"thrd_equal": {
- "defined": "7.28.5.4"
+ "c-definition": "7.28.5.4"
},
"thrd_exit": {
- "defined": "7.28.5.5"
+ "c-definition": "7.28.5.5"
},
"thrd_join": {
- "defined": "7.28.5.6"
+ "c-definition": "7.28.5.6"
},
"thrd_sleep": {
- "defined": "7.28.5.7"
+ "c-definition": "7.28.5.7"
},
"thrd_yield": {
- "defined": "7.28.5.8"
+ "c-definition": "7.28.5.8"
},
"tss_create": {
- "defined": "7.28.6.1"
+ "c-definition": "7.28.6.1"
},
"tss_delete": {
- "defined": "7.28.6.2"
+ "c-definition": "7.28.6.2"
},
"tss_get": {
- "defined": "7.28.6.3"
+ "c-definition": "7.28.6.3"
},
"tss_set": {
- "defined": "7.28.6.4"
+ "c-definition": "7.28.6.4"
}
}
}
>From 857a3ee7c5f1f6ea7253dab18dc1fcb526869e0d Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 15:48:18 -0500
Subject: [PATCH 2/9] Remove typo in docgen.py docs
Co-authored-by: Nick Desaulniers <nickdesaulniers at users.noreply.github.com>
---
libc/utils/docgen/docgen.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 43fa6c8e3dfcf2..ac62558c51a824 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -29,7 +29,7 @@ class Header:
file somewhere in the directory tree with root at
``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros``. Docgen expects that
if a macro is implemented, that it appears in a string
- ``#define MACRO_NAME`` in some ``*-macros.h`` file in the directory tree..
+ ``#define MACRO_NAME`` in some ``*-macros.h`` file in the directory tree.
Docgen searches for this string in the file to set the implementation status
shown in the generated rst docs rendered as html for display at
<libc.llvm.org>.
>From fd63dce806442ba9183c8199b9ab5e8a95beaf22 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 15:48:55 -0500
Subject: [PATCH 3/9] Refactor docgen.py header setting directories
Co-authored-by: Nick Desaulniers <nickdesaulniers at users.noreply.github.com>
---
libc/utils/docgen/docgen.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index ac62558c51a824..cf6529e19d9152 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -49,8 +49,8 @@ def __init__(self, header_name: str):
"""
self.name = header_name
self.stem = header_name.rstrip(".h")
- self.libc_root = Path(__file__).parent.parent.parent
self.docgen_root = Path(__file__).parent
+ self.libc_root = self.docgen_root.parent.parent
self.docgen_json = self.docgen_root / Path(header_name).with_suffix(".json")
self.fns_dir = Path(self.libc_root, "src", self.stem)
self.macros_dir = Path(self.libc_root, "include", "llvm-libc-macros")
>From 0833de193ad21a1f83587dfcde61a458d6a018a4 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 16:04:33 -0500
Subject: [PATCH 4/9] move docgen Header class to a separate module
---
libc/utils/docgen/__init__.py | 7 +++
libc/utils/docgen/docgen.py | 78 ++--------------------------------
libc/utils/docgen/header.py | 80 +++++++++++++++++++++++++++++++++++
3 files changed, 91 insertions(+), 74 deletions(-)
create mode 100644 libc/utils/docgen/__init__.py
create mode 100644 libc/utils/docgen/header.py
diff --git a/libc/utils/docgen/__init__.py b/libc/utils/docgen/__init__.py
new file mode 100644
index 00000000000000..1bba8b44c060c7
--- /dev/null
+++ b/libc/utils/docgen/__init__.py
@@ -0,0 +1,7 @@
+# ====- __init__.py for docgen -------------------------------*- python -*---==#
+#
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+# ==-------------------------------------------------------------------------==#
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index cf6529e19d9152..f7168044cc6e94 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -9,87 +9,17 @@
# ==-------------------------------------------------------------------------==#
from argparse import ArgumentParser, Namespace
from pathlib import Path
-from typing import Dict, Generator
+from typing import Dict
import sys
import json
+from header import Header
+
class DocgenAPIFormatError(Exception):
"""Raised on fatal formatting errors with a description of a formatting error"""
-
-class Header:
- """
- Maintains implementation information about a standard header file:
- * where does its implementation dir live
- * where is its macros file
- * where is its docgen json file
-
- By convention, the macro-only part of a header file is in a header-specific
- file somewhere in the directory tree with root at
- ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros``. Docgen expects that
- if a macro is implemented, that it appears in a string
- ``#define MACRO_NAME`` in some ``*-macros.h`` file in the directory tree.
- Docgen searches for this string in the file to set the implementation status
- shown in the generated rst docs rendered as html for display at
- <libc.llvm.org>.
-
- By convention, each function for a header is implemented in a function-specific
- cpp file somewhere in the directory tree with root at, e.g,
- ``$LLVM_PROJECT_ROOT/libc/src/fenv``. Some headers have architecture-specific
- implementations, like ``math``, and some don't, like ``fenv``. Docgen uses the
- presence of this function-specific cpp file to set the implementation status
- shown in the generated rst docs rendered as html for display at
- <libc.llvm.org>.
- """
-
- def __init__(self, header_name: str):
- """
- :param header_name: e.g., ``"threads.h"`` or ``"signal.h"``
- """
- self.name = header_name
- self.stem = header_name.rstrip(".h")
- self.docgen_root = Path(__file__).parent
- self.libc_root = self.docgen_root.parent.parent
- self.docgen_json = self.docgen_root / Path(header_name).with_suffix(".json")
- self.fns_dir = Path(self.libc_root, "src", self.stem)
- self.macros_dir = Path(self.libc_root, "include", "llvm-libc-macros")
-
- def macro_file_exists(self) -> bool:
- for _ in self.__get_macro_files():
- return True
-
- return False
-
- def fns_dir_exists(self) -> bool:
- return self.fns_dir.exists() and self.fns_dir.is_dir()
-
- def implements_fn(self, fn_name: str) -> bool:
- for _ in self.fns_dir.glob(f"**/{fn_name}.cpp"):
- return True
-
- return False
-
- def implements_macro(self, m_name: str) -> bool:
- """
- Some macro files are in, e.g.,
- ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/fenv-macros.h``,
- but others are in subdirectories, e.g., ``signal.h`` has the macro
- definitions in
- ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/linux/signal-macros.h``.
-
- :param m_name: name of macro, e.g., ``FE_ALL_EXCEPT``
- """
- for f in self.__get_macro_files():
- if f"#define {m_name}" in f.read_text():
- return True
-
- return False
-
- def __get_macro_files(self) -> Generator[Path, None, None]:
- return self.macros_dir.glob(f"**/{self.stem}-macros.h")
-
-
+
def check_api(header: Header, api: Dict):
"""
Checks that docgen json files are properly formatted. If there are any
diff --git a/libc/utils/docgen/header.py b/libc/utils/docgen/header.py
new file mode 100644
index 00000000000000..7d1e4ebe582143
--- /dev/null
+++ b/libc/utils/docgen/header.py
@@ -0,0 +1,80 @@
+# ====- Information about standard headers used by docgen ----*- python -*--==#
+#
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+# ==-------------------------------------------------------------------------==#
+from pathlib import Path
+from typing import Generator
+
+class Header:
+ """
+ Maintains implementation information about a standard header file:
+ * where does its implementation dir live
+ * where is its macros file
+ * where is its docgen json file
+
+ By convention, the macro-only part of a header file is in a header-specific
+ file somewhere in the directory tree with root at
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros``. Docgen expects that
+ if a macro is implemented, that it appears in a string
+ ``#define MACRO_NAME`` in some ``*-macros.h`` file in the directory tree.
+ Docgen searches for this string in the file to set the implementation status
+ shown in the generated rst docs rendered as html for display at
+ <libc.llvm.org>.
+
+ By convention, each function for a header is implemented in a function-specific
+ cpp file somewhere in the directory tree with root at, e.g,
+ ``$LLVM_PROJECT_ROOT/libc/src/fenv``. Some headers have architecture-specific
+ implementations, like ``math``, and some don't, like ``fenv``. Docgen uses the
+ presence of this function-specific cpp file to set the implementation status
+ shown in the generated rst docs rendered as html for display at
+ <libc.llvm.org>.
+ """
+
+ def __init__(self, header_name: str):
+ """
+ :param header_name: e.g., ``"threads.h"`` or ``"signal.h"``
+ """
+ self.name = header_name
+ self.stem = header_name.rstrip(".h")
+ self.docgen_root = Path(__file__).parent
+ self.libc_root = self.docgen_root.parent.parent
+ self.docgen_json = self.docgen_root / Path(header_name).with_suffix(".json")
+ self.fns_dir = Path(self.libc_root, "src", self.stem)
+ self.macros_dir = Path(self.libc_root, "include", "llvm-libc-macros")
+
+ def macro_file_exists(self) -> bool:
+ for _ in self.__get_macro_files():
+ return True
+
+ return False
+
+ def fns_dir_exists(self) -> bool:
+ return self.fns_dir.exists() and self.fns_dir.is_dir()
+
+ def implements_fn(self, fn_name: str) -> bool:
+ for _ in self.fns_dir.glob(f"**/{fn_name}.cpp"):
+ return True
+
+ return False
+
+ def implements_macro(self, m_name: str) -> bool:
+ """
+ Some macro files are in, e.g.,
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/fenv-macros.h``,
+ but others are in subdirectories, e.g., ``signal.h`` has the macro
+ definitions in
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/linux/signal-macros.h``.
+
+ :param m_name: name of macro, e.g., ``FE_ALL_EXCEPT``
+ """
+ for f in self.__get_macro_files():
+ if f"#define {m_name}" in f.read_text():
+ return True
+
+ return False
+
+ def __get_macro_files(self) -> Generator[Path, None, None]:
+ return self.macros_dir.glob(f"**/{self.stem}-macros.h")
>From fdea97de404f14fd951df1789449910d9c51f79d Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 16:10:22 -0500
Subject: [PATCH 5/9] address review comments
---
libc/utils/docgen/docgen.py | 2 +-
libc/utils/docgen/header.py | 6 ++++++
2 files changed, 7 insertions(+), 1 deletion(-)
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index f7168044cc6e94..1b582c7b3a7c40 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -157,6 +157,7 @@ def print_macros_rst(header: Header, macros: Dict):
print(f' - {macros[name]["posix-definition"]}')
else:
print(" -")
+ print()
def print_impl_status_rst(header: Header, api: Dict):
@@ -170,7 +171,6 @@ def print_impl_status_rst(header: Header, api: Dict):
# the macro and function sections are both optional
if "macros" in api:
print_macros_rst(header, api["macros"])
- print()
if "functions" in api:
print_functions_rst(header, api["functions"])
diff --git a/libc/utils/docgen/header.py b/libc/utils/docgen/header.py
index 7d1e4ebe582143..3b03a14e5f184a 100644
--- a/libc/utils/docgen/header.py
+++ b/libc/utils/docgen/header.py
@@ -77,4 +77,10 @@ def implements_macro(self, m_name: str) -> bool:
return False
def __get_macro_files(self) -> Generator[Path, None, None]:
+ """
+ This function uses a glob on, e.g., ``"**/fcntl.macros.h"`` because the
+ macro file might be located in a subdirectory:
+ libc/include/llvm-libc-macros/fcntl-macros.h
+ libc/include/llvm-libc-macros/linux/fcntl-macros.h
+ """
return self.macros_dir.glob(f"**/{self.stem}-macros.h")
>From a3fb6a2de3809a2c769ecc481a8e316b389f7653 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 16:13:07 -0500
Subject: [PATCH 6/9] black formatting
---
libc/utils/docgen/docgen.py | 2 +-
libc/utils/docgen/header.py | 1 +
2 files changed, 2 insertions(+), 1 deletion(-)
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 1b582c7b3a7c40..a7e4c5ba1c2792 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -19,7 +19,7 @@
class DocgenAPIFormatError(Exception):
"""Raised on fatal formatting errors with a description of a formatting error"""
-
+
def check_api(header: Header, api: Dict):
"""
Checks that docgen json files are properly formatted. If there are any
diff --git a/libc/utils/docgen/header.py b/libc/utils/docgen/header.py
index 3b03a14e5f184a..dde210078db278 100644
--- a/libc/utils/docgen/header.py
+++ b/libc/utils/docgen/header.py
@@ -8,6 +8,7 @@
from pathlib import Path
from typing import Generator
+
class Header:
"""
Maintains implementation information about a standard header file:
>From 9fb808a48064b88e3d2f80a8531141d6496d8eb6 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 16:50:26 -0500
Subject: [PATCH 7/9] wip: long table names
---
libc/docs/ctype.rst | 4 ++--
libc/docs/fenv.rst | 8 ++++----
libc/docs/signal.rst | 8 ++++----
libc/docs/stdbit.rst | 8 ++++----
libc/docs/threads.rst | 8 ++++----
libc/utils/docgen/docgen.py | 4 ++--
6 files changed, 20 insertions(+), 20 deletions(-)
diff --git a/libc/docs/ctype.rst b/libc/docs/ctype.rst
index e87116f10bfbdf..d55d63d75a7c83 100644
--- a/libc/docs/ctype.rst
+++ b/libc/docs/ctype.rst
@@ -14,8 +14,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - isalnum
- |check|
- 7.4.1.1
diff --git a/libc/docs/fenv.rst b/libc/docs/fenv.rst
index 22bef37d9c8440..16fae27cb2c0aa 100644
--- a/libc/docs/fenv.rst
+++ b/libc/docs/fenv.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - FE_ALL_EXCEPT
- |check|
- 7.6.12
@@ -103,8 +103,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - fe_dec_getround
-
- 7.6.5.3
diff --git a/libc/docs/signal.rst b/libc/docs/signal.rst
index 15d0aaaae3400d..8e7a1a94a117d9 100644
--- a/libc/docs/signal.rst
+++ b/libc/docs/signal.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - SIGABRT
- |check|
- 7.14.3
@@ -163,8 +163,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - kill
- |check|
-
diff --git a/libc/docs/stdbit.rst b/libc/docs/stdbit.rst
index 47c3a00e2ba6c8..c565b3fc296ea4 100644
--- a/libc/docs/stdbit.rst
+++ b/libc/docs/stdbit.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - __STDC_ENDIAN_BIG__
- |check|
- 7.18.2.2
@@ -99,8 +99,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - stdc_bit_ceil_uc
- |check|
- 7.18.16
diff --git a/libc/docs/threads.rst b/libc/docs/threads.rst
index 360b29a64abd87..2818afed11fa7b 100644
--- a/libc/docs/threads.rst
+++ b/libc/docs/threads.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - ONCE_FLAG_INIT
-
- 7.28.1.3
@@ -35,8 +35,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - call_once
- |check|
- 7.28.2.1
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index a7e4c5ba1c2792..a3beef27c3b35f 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -102,8 +102,8 @@ def print_tbl_dir():
* - Function
- Implemented
- - C Standard
- - POSIX Standard"""
+ - C23 Standard Section
+ - POSIX 2018 Standard Section"""
)
>From c38a5a9395a63245bf42d1c89c9735cf09c56ac2 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 18:40:30 -0500
Subject: [PATCH 8/9] remove empty __init__.py
---
libc/utils/docgen/__init__.py | 7 -------
1 file changed, 7 deletions(-)
delete mode 100644 libc/utils/docgen/__init__.py
diff --git a/libc/utils/docgen/__init__.py b/libc/utils/docgen/__init__.py
deleted file mode 100644
index 1bba8b44c060c7..00000000000000
--- a/libc/utils/docgen/__init__.py
+++ /dev/null
@@ -1,7 +0,0 @@
-# ====- __init__.py for docgen -------------------------------*- python -*---==#
-#
-# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
-# See https://llvm.org/LICENSE.txt for license information.
-# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
-#
-# ==-------------------------------------------------------------------------==#
>From 255064b77697c581d7d59a9004afaadf84e2539d Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 18:42:31 -0500
Subject: [PATCH 9/9] Revert "wip: long table names"
This reverts commit 9fb808a48064b88e3d2f80a8531141d6496d8eb6.
Did not mean to commit this.
---
libc/docs/ctype.rst | 4 ++--
libc/docs/fenv.rst | 8 ++++----
libc/docs/signal.rst | 8 ++++----
libc/docs/stdbit.rst | 8 ++++----
libc/docs/threads.rst | 8 ++++----
libc/utils/docgen/docgen.py | 4 ++--
6 files changed, 20 insertions(+), 20 deletions(-)
diff --git a/libc/docs/ctype.rst b/libc/docs/ctype.rst
index d55d63d75a7c83..e87116f10bfbdf 100644
--- a/libc/docs/ctype.rst
+++ b/libc/docs/ctype.rst
@@ -14,8 +14,8 @@ Functions
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - isalnum
- |check|
- 7.4.1.1
diff --git a/libc/docs/fenv.rst b/libc/docs/fenv.rst
index 16fae27cb2c0aa..22bef37d9c8440 100644
--- a/libc/docs/fenv.rst
+++ b/libc/docs/fenv.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - FE_ALL_EXCEPT
- |check|
- 7.6.12
@@ -103,8 +103,8 @@ Functions
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - fe_dec_getround
-
- 7.6.5.3
diff --git a/libc/docs/signal.rst b/libc/docs/signal.rst
index 8e7a1a94a117d9..15d0aaaae3400d 100644
--- a/libc/docs/signal.rst
+++ b/libc/docs/signal.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - SIGABRT
- |check|
- 7.14.3
@@ -163,8 +163,8 @@ Functions
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - kill
- |check|
-
diff --git a/libc/docs/stdbit.rst b/libc/docs/stdbit.rst
index c565b3fc296ea4..47c3a00e2ba6c8 100644
--- a/libc/docs/stdbit.rst
+++ b/libc/docs/stdbit.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - __STDC_ENDIAN_BIG__
- |check|
- 7.18.2.2
@@ -99,8 +99,8 @@ Functions
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - stdc_bit_ceil_uc
- |check|
- 7.18.16
diff --git a/libc/docs/threads.rst b/libc/docs/threads.rst
index 2818afed11fa7b..360b29a64abd87 100644
--- a/libc/docs/threads.rst
+++ b/libc/docs/threads.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - ONCE_FLAG_INIT
-
- 7.28.1.3
@@ -35,8 +35,8 @@ Functions
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - call_once
- |check|
- 7.28.2.1
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index a3beef27c3b35f..a7e4c5ba1c2792 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -102,8 +102,8 @@ def print_tbl_dir():
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section"""
+ - C Standard
+ - POSIX Standard"""
)
More information about the libc-commits
mailing list