Jump to conversation
Unresolved conversations (4)
@nickdesaulniers nickdesaulniers Apr 22, 2024
This URL is LOOOOONNNGG. Maybe we can think of ways to shorten it in the config files. (We don't need to do that in this PR). But IIRC the URL is slightly error prone because folks might accidentally link to older POSIX standards. (They might have to for some things that were REMOVED from POSIX; not sure what, but I heard that's the case. I will research that more). But I do see a convention like our "functions" have `/functions/` in the URL. Hmm...yeah, let's worry about that in a follow up (not this PR).
libc/utils/docgen/signal.json
@nickdesaulniers nickdesaulniers Apr 22, 2024
Hmm...the current wording makes me think "what C standard or POSIX standard was this first defined in" which is how the man pages project documents these, but NOT what we're doing for docgen. Let's discuss (in this comment thread, before you post changes to wording) some different ways we can make that clearer. Perhaps: - C23 Standard Section - POSIX Docs Would make our intent clearer? Got any other ideas?
Outdated
libc/utils/docgen/docgen.py
@nickdesaulniers nickdesaulniers Apr 22, 2024
So this would trigger if someone adds documentation for foo.h but there's no libc/src/foo/ ? I think that should be ok and we should not diagnose that. That way, documentation can proceed orthogonal to implementation.
libc/utils/docgen/docgen.py
@nickdesaulniers nickdesaulniers Apr 22, 2024
I don't see the `src` dir going away any time soon. If this is simply checking for the existence of `libc/src`, consider omitting this check so that we have less code to maintain in docgen.
Outdated
libc/utils/docgen/docgen.py
Resolved conversations (6)
@michaelrj-google michaelrj-google Apr 22, 2024
is there a reason to have this empty file?
Outdated
libc/utils/docgen/__init__.py
@nickdesaulniers nickdesaulniers Apr 22, 2024
move this print into print_macros_rst?
Outdated
libc/utils/docgen/docgen.py
@nickdesaulniers nickdesaulniers Apr 22, 2024
I like this class. Consider moving it to a new file in the docgen dir and importing it into this file.
Outdated
libc/utils/docgen/docgen.py
@nickdesaulniers nickdesaulniers Apr 22, 2024
Please add a comment that this uses `glob` with `**` because we might have something like: - libc/include/llvm-libc-macros/fcntl-macros.h - libc/include/llvm-libc-macros/linux/fcntl-macros.h
Outdated
libc/utils/docgen/docgen.py
@nickdesaulniers nickdesaulniers Apr 22, 2024
```suggestion self.docgen_root = Path(__file__).parent self.libc_root = self.docgen_root.parent.parent ```
Outdated
libc/utils/docgen/docgen.py
@nickdesaulniers nickdesaulniers Apr 22, 2024
```suggestion ``#define MACRO_NAME`` in some ``*-macros.h`` file in the directory tree. ```
Outdated
libc/utils/docgen/docgen.py