[libc-commits] [libc] [libc][docs] Updates implementation status for some preexisting docgen json files (PR #89281)

[Nick Desaulniers via libc-commits]

================
@@ -1,29 +1,56 @@
 {
-  "macros": [
-    "SIG_DFL",
-    "SIG_ERR",
-    "SIG_IGN",
-    "SIGABRT",
-    "SIGFPE",
-    "SIGILL",
-    "SIGINT",
-    "SIGSEGV",
-    "SIGTERM"
-  ],
+  "macros": {
+    "SIG_DFL": {
+      "defined": "7.14.3",
+      "implemented": false
+    },
+    "SIG_ERR": {
+      "defined": "7.14.3",
+      "implemented": false
+    },
+    "SIG_IGN": {
+      "defined": "7.14.3",
+      "implemented": false
+    },
+    "SIGABRT": {
+      "defined": "7.14.3",
+      "implemented": true
+    },
+    "SIGFPE": {
+      "defined": "7.14.3",
+      "implemented": true
+    },
+    "SIGILL": {
+      "defined": "7.14.3",
+      "implemented": true
+    },
+    "SIGINT": {
+      "defined": "7.14.3",
+      "implemented": true
+    },
+    "SIGSEGV": {
+      "defined": "7.14.3",
+      "implemented": true
+    },
+    "SIGTERM": {
+      "defined": "7.14.3",
+      "implemented": true
+    }
+  },
   "functions": {
+    "signal": {
+      "defined": "7.14.1.1"
+    },
+    "raise": {
+      "defined": "7.14.2.1"
+    },
----------------
nickdesaulniers wrote:

>  I was going to let the POSIX functions fall

POSIX-only

> docgen.py is sorting everything in the rst files alphabetically by function/macro name currently.

Yeah, I noticed.  I suspect the json parser is using ordered dictionaries.

I think my feeling here is: if it's easy to sort via automation, keep it sorted. Otherwise, whatever. At least for the config files.

> Order in the rst docs seems more, 'how will people use it'?

Right. Let's wait to collect feedback from more consumers before making a decision.  We could sort by C standard section for instance.  Then perhaps POSIX sections.  Let's hold on to that thought until later though.

---

> I was leaning towards the latter solution with distinct fields

SGTM

> do we need the standard numbers to differentiate C/POSIX standard versions?

So far, we're only tracking the latest accepted C standard.  You'll notice the sections jump around between C standard revisions because new functions get added in the middle of existing sections.

So I think we should do the same for POSIX and just refer to POSIX.1-2017.

IIUC some functions were deprecated by newer POSIX standards, but many programs won't be rewritten to reflect that, so most libc's need to provide even deprecated POSIX functionality to be somewhat portable-to.  IDK if POSIX has ever removed anything; in that case we'd have to point back to prior POSIX releases.

Let's ask the maintainer of bionic (Android's libc), @enh-google , if he knows answers to the above?

To me, currently, docgen is more about:
1. reflecting to users how "done" we are via some form of visualization (even if fragmented across numerous html pages)
2. visualizing what could be implemented next, either by the core team or new contributors.
3. helping implementers quickly know which section of which doc they should read to understand the semantics required by "the spec" for whichever specs are relevant.

Maybe someday docgen grows into more (such as when these things were first standardized), but I'd rather folks contribute to the upstream man pages project as duplicating what they have is frankly a waste of time and is user hostile.

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