Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[libc][docs] Updates implementation status for some preexisting docgen json files #89281
[libc][docs] Updates implementation status for some preexisting docgen json files #89281
Changes from 1 commit
a15bff7
22cd7f2
File filter
Filter by extension
Conversations
Jump to
There are no files selected for viewing
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I haven't decided yet how best to "sort" these.
I think we might even want to change the "schema" for defined because:
Due to 2, these should ultimately be a list, or perhaps another object with distinct fields for C standard section number and hyperlink to POSIX docs (or linux man pages, for other APIs even).
I guess orthogonal to that though, is how do we want to keep things "in order" in the config files, and/or in the generated rst files?
If I can't highlight rows in vim and simply
:sort
, then maintaining a sort manually is a PITA. So I don't think we need to maintain or require sorting the json configs.I guess a lot of bloviating, but all that to ask what is your reasoning here for moving signal+raise and do we need to change the current sort here in this PR?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have no strong opinions on the orderings. Based on the previous files, I've been keeping the json files in order of occurrence in the C standard for ease of auditing alongside the standard. This is why I bumped signal and raise up, I was going to let the POSIX functions fall after but totally fine with reverting or alphabetically sorting.
docgen.py
is sorting everything in therst
files alphabetically by function/macro name currently. Order in the rst docs seems more, 'how will people use it'?Yeah, I haven't started on listing POSIX hyperlinks yet. I was leaning towards the latter solution with distinct fields and changing
docgen.py
to: change the "Standard" rst column to "C23 Standard", add an optionalPOSIX standard#
column (do we need the standard numbers to differentiate C/POSIX standard versions?) that is only added to the generated rst if some row has a POSIX reference in the json.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
POSIX-only
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.
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.
SGTM
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:
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I thought the current sorting in the generated rst docs was on purpose, there is an explicit sort on function names.
Another ordering to take into account, that does bug me a bit, is the ordering of the listed headers in the left side bar on libc.llvm.org: "Search Tables" and "C23 Support" in the middle of the standard headers. Thoughts on reordering these to push the standard header status to the bottom on the side bar and alphabetically sorted?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes, POSIX has removed things. no, most C libraries do not remove those things.
i regret all of the functions i removed. it didn't gain me anything (because we'd already done the work), and it hurt developers (if only slightly).
that said, i do not regret the ones i never added https://android.googlesource.com/platform/bionic/+/main/docs/status.md#posix --- POSIX is full of useless crap while also missing lots of essential stuff. (theoretically that makes sense viewed from their "codifying existing practice" stance, but at the same time they remove tar(1) in favor of pax(1), or add gzip to compress(1) rather than add gzip(1), so their grasp of "existing practice" is tenuous at best.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, that's right. I wrote that. Either way, I don't have my heart set on that. What's more important to me is that we maintain some form of determinism in output in case folks decide to re-arrange the order of things in json. Though maybe we just keep the json sorted (painful) and rely on that ordering. Personally, I think it'll be easier to enforce the ordering if the tool just sorts every time, then we can add new stuff to the json in any order.
heh, I was just talking with @dpxf about that. yeah it's ugly and will grow to be unwieldy very quickly. I'd like to have one tab, that links to a newly created page, that lists each header we provide, which is a link to the corresponding page.