[libc][docs][POSIX] flush out documentation for the POSIX defined headers
#122 006 ouverte le 7 janv. 2025
Métriques du dépôt
- Stars
- (26 378 stars)
- Métriques de merge PR
- (Merge moyen 1j 2h) (1 000 PRs mergées en 30 j)
Description
If you go to https://pubs.opengroup.org/onlinepubs/9799919799/, then 14. Headers in the bottom left, you get a list of headers mandated by POSIX. I'd like to document them from https://libc.llvm.org/headers/index.html. We do so by manually curating some metadata about functions and preprocessor defines in yaml files. The yaml files are currently in https://github.com/llvm/llvm-project/tree/main/libc/utils/docgen. https://github.com/llvm/llvm-project/blob/main/libc/utils/docgen/arpa/inet.yaml is an example of arpa/inet.h as per POSIX. POSIX also tries to be a superset of C (though FWICT POSIX1.2024 missed C23 additions...), so most headers we have entries for already (though we should triple check since POSIX can add functions to existing C standard headers).
Once we've added entries for the new POSIX headers, you should configure your build with the 2 additional cmake flags:
-DLLVM_ENABLE_SPHINX=ON-DLIBC_INCLUDE_DOCS=ON
Then you can do ninja docs-libc-html to build html you can view locally in {build_dir}/libc/docs/html/headers/**.html.
Good pull requests should implement one header at a time, and not send a PR that implements documentation for more than one header at a time. If that means that this issue is a "meta" issue for which multiple PRs will link against, so be it.