[libc-commits] [libc] docs c89 (PR #118852)
Nick Desaulniers via libc-commits
libc-commits at lists.llvm.org
Thu Dec 5 10:14:07 PST 2024
https://github.com/nickdesaulniers created https://github.com/llvm/llvm-project/pull/118852
- **[libc][docs] reorganize documentation**
- **[libc][docs] stub out assert, errno, and locale**
>From 14590c83dd672f699642292cfbe44e54144b49c6 Mon Sep 17 00:00:00 2001
From: Nick Desaulniers <ndesaulniers at google.com>
Date: Thu, 5 Dec 2024 09:12:54 -0800
Subject: [PATCH 1/2] [libc][docs] reorganize documentation
This commit does a few things:
* creates libc/docs/headers/ and moves all user API related headers under it.
* updates paths and docgen
* updates the top level index to put these headers under a new "Implementation
Status" tab.
* rename some of the files to be foo.rst for foo.h (except strings, which is
currently a mix of string.h and stdlib.h)
* update the heading of some files to be in the form foo.h.
---
libc/docs/{ => headers}/complex.rst | 2 +-
libc/docs/{ => headers}/ctype.rst | 2 +-
libc/docs/{ => headers}/fenv.rst | 2 +-
libc/docs/headers/index.rst | 18 ++++++++++++++++++
libc/docs/{ => headers}/math/index.rst | 8 ++++----
libc/docs/{ => headers}/math/log.rst | 0
libc/docs/{ => headers}/math/stdfix.rst | 2 +-
.../{libc_search.rst => headers/search.rst} | 8 ++++----
libc/docs/{ => headers}/setjmp.rst | 2 +-
libc/docs/{ => headers}/signal.rst | 2 +-
libc/docs/{ => headers}/stdbit.rst | 2 +-
libc/docs/{ => headers}/stdio.rst | 8 ++++----
libc/docs/{ => headers}/strings.rst | 2 +-
libc/docs/{ => headers}/threads.rst | 2 +-
.../{date_and_time.rst => headers/time.rst} | 8 ++++----
libc/docs/index.rst | 13 +------------
libc/utils/docgen/docgen.py | 2 +-
17 files changed, 45 insertions(+), 38 deletions(-)
rename libc/docs/{ => headers}/complex.rst (99%)
rename libc/docs/{ => headers}/ctype.rst (97%)
rename libc/docs/{ => headers}/fenv.rst (98%)
create mode 100644 libc/docs/headers/index.rst
rename libc/docs/{ => headers}/math/index.rst (99%)
rename libc/docs/{ => headers}/math/log.rst (100%)
rename libc/docs/{ => headers}/math/stdfix.rst (99%)
rename libc/docs/{libc_search.rst => headers/search.rst} (95%)
rename libc/docs/{ => headers}/setjmp.rst (95%)
rename libc/docs/{ => headers}/signal.rst (99%)
rename libc/docs/{ => headers}/stdbit.rst (99%)
rename libc/docs/{ => headers}/stdio.rst (96%)
rename libc/docs/{ => headers}/strings.rst (99%)
rename libc/docs/{ => headers}/threads.rst (98%)
rename libc/docs/{date_and_time.rst => headers/time.rst} (99%)
diff --git a/libc/docs/complex.rst b/libc/docs/headers/complex.rst
similarity index 99%
rename from libc/docs/complex.rst
rename to libc/docs/headers/complex.rst
index 1e74f16b60e660..2e81aba97b0ef6 100644
--- a/libc/docs/complex.rst
+++ b/libc/docs/headers/complex.rst
@@ -1,4 +1,4 @@
-.. include:: check.rst
+.. include:: ../check.rst
=========
complex.h
diff --git a/libc/docs/ctype.rst b/libc/docs/headers/ctype.rst
similarity index 97%
rename from libc/docs/ctype.rst
rename to libc/docs/headers/ctype.rst
index 66e6f12b87818c..e506830809f795 100644
--- a/libc/docs/ctype.rst
+++ b/libc/docs/headers/ctype.rst
@@ -1,4 +1,4 @@
-.. include:: check.rst
+.. include:: ../check.rst
=======
ctype.h
diff --git a/libc/docs/fenv.rst b/libc/docs/headers/fenv.rst
similarity index 98%
rename from libc/docs/fenv.rst
rename to libc/docs/headers/fenv.rst
index d910ba8852f68c..374b46ef57be0a 100644
--- a/libc/docs/fenv.rst
+++ b/libc/docs/headers/fenv.rst
@@ -1,4 +1,4 @@
-.. include:: check.rst
+.. include:: ../check.rst
======
fenv.h
diff --git a/libc/docs/headers/index.rst b/libc/docs/headers/index.rst
new file mode 100644
index 00000000000000..2a7bf59e0b56db
--- /dev/null
+++ b/libc/docs/headers/index.rst
@@ -0,0 +1,18 @@
+Implementation Status
+=====================
+
+.. toctree::
+ :maxdepth: 1
+
+ complex
+ ctype
+ fenv
+ math/index.rst
+ search
+ setjmp
+ signal
+ stdbit
+ stdio
+ strings
+ threads
+ time
diff --git a/libc/docs/math/index.rst b/libc/docs/headers/math/index.rst
similarity index 99%
rename from libc/docs/math/index.rst
rename to libc/docs/headers/math/index.rst
index 4934e93ccb1645..adc0afa080ec2a 100644
--- a/libc/docs/math/index.rst
+++ b/libc/docs/headers/math/index.rst
@@ -1,10 +1,10 @@
.. _math:
-==============
-Math Functions
-==============
+======
+math.h
+======
-.. include:: ../check.rst
+.. include:: ../../check.rst
.. raw:: html
diff --git a/libc/docs/math/log.rst b/libc/docs/headers/math/log.rst
similarity index 100%
rename from libc/docs/math/log.rst
rename to libc/docs/headers/math/log.rst
diff --git a/libc/docs/math/stdfix.rst b/libc/docs/headers/math/stdfix.rst
similarity index 99%
rename from libc/docs/math/stdfix.rst
rename to libc/docs/headers/math/stdfix.rst
index d8dcb0cfa4c521..58052f000995cd 100644
--- a/libc/docs/math/stdfix.rst
+++ b/libc/docs/headers/math/stdfix.rst
@@ -2,7 +2,7 @@
StdFix Functions
================
-.. include:: ../check.rst
+.. include:: ../../check.rst
Standards and Goals
-------------------
diff --git a/libc/docs/libc_search.rst b/libc/docs/headers/search.rst
similarity index 95%
rename from libc/docs/libc_search.rst
rename to libc/docs/headers/search.rst
index 774622d1e66c3f..51832e9bdc2ed4 100644
--- a/libc/docs/libc_search.rst
+++ b/libc/docs/headers/search.rst
@@ -1,8 +1,8 @@
-=============
-Search Tables
-=============
+========
+search.h
+========
-.. include:: check.rst
+.. include:: ../check.rst
---------------
Source Location
diff --git a/libc/docs/setjmp.rst b/libc/docs/headers/setjmp.rst
similarity index 95%
rename from libc/docs/setjmp.rst
rename to libc/docs/headers/setjmp.rst
index 3739e73685b4bb..b0091134f1a6b2 100644
--- a/libc/docs/setjmp.rst
+++ b/libc/docs/headers/setjmp.rst
@@ -1,4 +1,4 @@
-.. include:: check.rst
+.. include:: ../check.rst
========
setjmp.h
diff --git a/libc/docs/signal.rst b/libc/docs/headers/signal.rst
similarity index 99%
rename from libc/docs/signal.rst
rename to libc/docs/headers/signal.rst
index 172dd4a048ae9a..b59ae093423574 100644
--- a/libc/docs/signal.rst
+++ b/libc/docs/headers/signal.rst
@@ -1,4 +1,4 @@
-.. include:: check.rst
+.. include:: ../check.rst
========
signal.h
diff --git a/libc/docs/stdbit.rst b/libc/docs/headers/stdbit.rst
similarity index 99%
rename from libc/docs/stdbit.rst
rename to libc/docs/headers/stdbit.rst
index 3718ff8dc0df26..0484d951e19c6b 100644
--- a/libc/docs/stdbit.rst
+++ b/libc/docs/headers/stdbit.rst
@@ -1,4 +1,4 @@
-.. include:: check.rst
+.. include:: ../check.rst
========
stdbit.h
diff --git a/libc/docs/stdio.rst b/libc/docs/headers/stdio.rst
similarity index 96%
rename from libc/docs/stdio.rst
rename to libc/docs/headers/stdio.rst
index d17821562c2556..3cd355529d4005 100644
--- a/libc/docs/stdio.rst
+++ b/libc/docs/headers/stdio.rst
@@ -1,8 +1,8 @@
-===============
-StdIO Functions
-===============
+=======
+stdio.h
+=======
-.. include:: check.rst
+.. include:: ../check.rst
---------------
Source location
diff --git a/libc/docs/strings.rst b/libc/docs/headers/strings.rst
similarity index 99%
rename from libc/docs/strings.rst
rename to libc/docs/headers/strings.rst
index 427644c407ae83..949c53bfa4f740 100644
--- a/libc/docs/strings.rst
+++ b/libc/docs/headers/strings.rst
@@ -2,7 +2,7 @@
String Functions
================
-.. include:: check.rst
+.. include:: ../check.rst
---------------
Source location
diff --git a/libc/docs/threads.rst b/libc/docs/headers/threads.rst
similarity index 98%
rename from libc/docs/threads.rst
rename to libc/docs/headers/threads.rst
index db2d6630a238c0..39ee049eb1f8f5 100644
--- a/libc/docs/threads.rst
+++ b/libc/docs/headers/threads.rst
@@ -1,4 +1,4 @@
-.. include:: check.rst
+.. include:: ../check.rst
=========
threads.h
diff --git a/libc/docs/date_and_time.rst b/libc/docs/headers/time.rst
similarity index 99%
rename from libc/docs/date_and_time.rst
rename to libc/docs/headers/time.rst
index b745a3b416f802..de82d80a2bec48 100644
--- a/libc/docs/date_and_time.rst
+++ b/libc/docs/headers/time.rst
@@ -1,8 +1,8 @@
-=======================
-Date and Time Functions
-=======================
+======
+time.h
+======
-.. include:: check.rst
+.. include:: ../check.rst
---------------
Source location
diff --git a/libc/docs/index.rst b/libc/docs/index.rst
index 6f759aa215b62c..01f36709dfa549 100644
--- a/libc/docs/index.rst
+++ b/libc/docs/index.rst
@@ -64,19 +64,8 @@ stages there is no ABI stability in any form.
:caption: Status
compiler_support
- date_and_time
- math/index.rst
- strings
- stdio
- stdbit
- fenv
- libc_search
+ headers/index.rst
c23
- ctype
- complex
- signal
- threads
- setjmp
.. toctree::
:hidden:
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 016a3dae9aaa0f..aa30a6e51ef870 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -161,7 +161,7 @@ def print_macros_rst(header: Header, macros: Dict):
def print_impl_status_rst(header: Header, api: Dict):
- print(".. include:: check.rst\n")
+ print(".. include:: ../check.rst\n")
print("=" * len(header.name))
print(header.name)
>From fdb8898406582f867bd84415d1ac830454b85237 Mon Sep 17 00:00:00 2001
From: Nick Desaulniers <ndesaulniers at google.com>
Date: Thu, 5 Dec 2024 10:11:28 -0800
Subject: [PATCH 2/2] [libc][docs] stub out assert, errno, and locale
These were the remaining c89 library headers (besides string.h and stdlib.h; I
will split strings.rst in a follow up commit).
The macro support detection in docgen doesn't quite work for some of these
headers. Add the stubs for these headers for now, and fix up docgen later.
See the "NIST publication":
Link: https://www.open-std.org/jtc1/sc22/wg14/www/projects.html
---
libc/docs/headers/assert.rst | 27 +++++++++++++++
libc/docs/headers/errno.rst | 35 +++++++++++++++++++
libc/docs/headers/index.rst | 3 ++
libc/docs/headers/locale.rst | 63 +++++++++++++++++++++++++++++++++++
libc/utils/docgen/assert.json | 10 ++++++
libc/utils/docgen/errno.json | 16 +++++++++
libc/utils/docgen/locale.json | 30 +++++++++++++++++
7 files changed, 184 insertions(+)
create mode 100644 libc/docs/headers/assert.rst
create mode 100644 libc/docs/headers/errno.rst
create mode 100644 libc/docs/headers/locale.rst
create mode 100644 libc/utils/docgen/assert.json
create mode 100644 libc/utils/docgen/errno.json
create mode 100644 libc/utils/docgen/locale.json
diff --git a/libc/docs/headers/assert.rst b/libc/docs/headers/assert.rst
new file mode 100644
index 00000000000000..06ea27966de1ae
--- /dev/null
+++ b/libc/docs/headers/assert.rst
@@ -0,0 +1,27 @@
+.. include:: ../check.rst
+
+========
+assert.h
+========
+
+Macros
+======
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Macro
+ - Implemented
+ - C23 Standard Section
+ - POSIX.1-2024 Standard Section
+ * - __STDC_VERSION_ASSERT_H__
+ - |check|
+ - 7.2.1
+ -
+ * - assert
+ -
+ - 7.2.1
+ -
+
diff --git a/libc/docs/headers/errno.rst b/libc/docs/headers/errno.rst
new file mode 100644
index 00000000000000..f25aae4f23b2c7
--- /dev/null
+++ b/libc/docs/headers/errno.rst
@@ -0,0 +1,35 @@
+.. include:: ../check.rst
+
+=======
+errno.h
+=======
+
+Macros
+======
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Macro
+ - Implemented
+ - C23 Standard Section
+ - POSIX.1-2024 Standard Section
+ * - EDOM
+ -
+ - 7.5
+ -
+ * - EILSEQ
+ -
+ - 7.5
+ -
+ * - ERANGE
+ -
+ - 7.5
+ -
+ * - errno
+ -
+ - 7.5
+ -
+
diff --git a/libc/docs/headers/index.rst b/libc/docs/headers/index.rst
index 2a7bf59e0b56db..7a9186a7c66e86 100644
--- a/libc/docs/headers/index.rst
+++ b/libc/docs/headers/index.rst
@@ -4,9 +4,12 @@ Implementation Status
.. toctree::
:maxdepth: 1
+ assert
complex
ctype
+ errno
fenv
+ locale
math/index.rst
search
setjmp
diff --git a/libc/docs/headers/locale.rst b/libc/docs/headers/locale.rst
new file mode 100644
index 00000000000000..2d5525bd3f2f9a
--- /dev/null
+++ b/libc/docs/headers/locale.rst
@@ -0,0 +1,63 @@
+.. include:: ../check.rst
+
+========
+locale.h
+========
+
+Macros
+======
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Macro
+ - Implemented
+ - C23 Standard Section
+ - POSIX.1-2024 Standard Section
+ * - LC_ALL
+ - |check|
+ - 7.11
+ -
+ * - LC_COLLATE
+ - |check|
+ - 7.11
+ -
+ * - LC_CTYPE
+ - |check|
+ - 7.11
+ -
+ * - LC_MONETARY
+ - |check|
+ - 7.11
+ -
+ * - LC_NUMERIC
+ - |check|
+ - 7.11
+ -
+ * - LC_TIME
+ - |check|
+ - 7.11
+ -
+
+Functions
+=========
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Function
+ - Implemented
+ - C23 Standard Section
+ - POSIX.1-2024 Standard Section
+ * - localeconv
+ - |check|
+ - 7.11.2.1
+ -
+ * - setlocale
+ - |check|
+ - 7.11.1.1
+ -
diff --git a/libc/utils/docgen/assert.json b/libc/utils/docgen/assert.json
new file mode 100644
index 00000000000000..28ec12028ef675
--- /dev/null
+++ b/libc/utils/docgen/assert.json
@@ -0,0 +1,10 @@
+{
+ "macros": {
+ "__STDC_VERSION_ASSERT_H__": {
+ "c-definition": "7.2.1"
+ },
+ "assert": {
+ "c-definition": "7.2.1"
+ }
+ }
+}
diff --git a/libc/utils/docgen/errno.json b/libc/utils/docgen/errno.json
new file mode 100644
index 00000000000000..aface8e42b495f
--- /dev/null
+++ b/libc/utils/docgen/errno.json
@@ -0,0 +1,16 @@
+{
+ "macros": {
+ "EDOM": {
+ "c-definition": "7.5"
+ },
+ "EILSEQ": {
+ "c-definition": "7.5"
+ },
+ "ERANGE": {
+ "c-definition": "7.5"
+ },
+ "errno": {
+ "c-definition": "7.5"
+ }
+ }
+}
diff --git a/libc/utils/docgen/locale.json b/libc/utils/docgen/locale.json
new file mode 100644
index 00000000000000..89329f9aae5b0f
--- /dev/null
+++ b/libc/utils/docgen/locale.json
@@ -0,0 +1,30 @@
+{
+ "macros": {
+ "LC_ALL": {
+ "c-definition": "7.11"
+ },
+ "LC_COLLATE": {
+ "c-definition": "7.11"
+ },
+ "LC_CTYPE": {
+ "c-definition": "7.11"
+ },
+ "LC_MONETARY": {
+ "c-definition": "7.11"
+ },
+ "LC_NUMERIC": {
+ "c-definition": "7.11"
+ },
+ "LC_TIME": {
+ "c-definition": "7.11"
+ }
+ },
+ "functions": {
+ "setlocale": {
+ "c-definition": "7.11.1.1"
+ },
+ "localeconv": {
+ "c-definition": "7.11.2.1"
+ }
+ }
+}
More information about the libc-commits
mailing list