From: Joseph Myers <joseph@codesourcery.com>
To: Florian Weimer <fweimer@redhat.com>
Cc: "H.J. Lu" <hjl.tools@gmail.com>,
Carlos O'Donell <carlos@redhat.com>,
GNU C Library <libc-alpha@sourceware.org>
Subject: Re: [PATCH] Add getcpu
Date: Wed, 05 Dec 2018 20:43:00 -0000 [thread overview]
Message-ID: <alpine.DEB.2.21.1812052028140.12928@digraph.polyomino.org.uk> (raw)
In-Reply-To: <877egng68l.fsf@oldenburg2.str.redhat.com>
On Wed, 5 Dec 2018, Florian Weimer wrote:
> We have a parallel discussion about a new requirement that all new
> functions must have documentation in the manual. I don't know what will
> come out of that.
It's not a new requirement at all. Documenting new interfaces was added
to <https://sourceware.org/glibc/wiki/Contribution%20checklist> on
2012-04-17.
There are questions about the details of when some function might be
excluded from being documented (such as if it's part of a family of
functions none of which are documented yet), and of how much documentation
should be included for a Linux-specific function whose main semantics
*are* to pass its arguments through to a Linux kernel syscall (but even
there you should document the argument and return types, error and
cancellation handling, what header declares the function under what
feature test macros - everything that is not part of the syscall interface
- even if one might link to external freely-licensed documentation of
exactly what the syscall does). But the basic principle that new
functions should be documented, in the absence of an explicitly stated
reason that documenting a given function is problematic, seems clear
enough - just like the principle that a new function should have test
coverage (in the absence of stated justification of being hard to test),
and that a new function needs a reason to be architecture-specific, for
example.
In this case, the proposed function has a prototype *different* from that
for the syscall, which makes it especially clear that documentation is
needed.
(The NEWS entry also needs to state that this function is Linux-specific.)
--
Joseph S. Myers
joseph@codesourcery.com
next prev parent reply other threads:[~2018-12-05 20:43 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-12-05 14:30 RFC: Add getcpu wrapper H.J. Lu
2018-12-05 15:35 ` Florian Weimer
2018-12-05 15:40 ` H.J. Lu
2018-12-05 15:49 ` Florian Weimer
2018-12-05 16:01 ` Zack Weinberg
2018-12-05 16:05 ` H.J. Lu
2018-12-05 17:33 ` Carlos O'Donell
2018-12-05 17:42 ` [PATCH] Add getcpu H.J. Lu
2018-12-05 18:14 ` H.J. Lu
2018-12-05 18:48 ` Florian Weimer
2018-12-05 19:51 ` H.J. Lu
2018-12-05 19:57 ` Florian Weimer
2018-12-05 20:07 ` H.J. Lu
2018-12-05 20:14 ` H.J. Lu
2018-12-07 12:51 ` Tulio Magno Quites Machado Filho
2018-12-07 16:51 ` H.J. Lu
2018-12-05 20:43 ` Joseph Myers [this message]
2018-12-05 20:56 ` The future of the manual (was Re: [PATCH] Add getcpu) Zack Weinberg
2018-12-05 21:29 ` Joseph Myers
2018-12-07 13:11 ` Florian Weimer
2018-12-05 21:40 ` [PATCH] Add getcpu H.J. Lu
2018-12-05 21:45 ` Joseph Myers
2018-12-05 21:55 ` Florian Weimer
2018-12-06 20:27 ` H.J. Lu
2018-12-07 16:52 ` Florian Weimer
2018-12-07 17:16 ` H.J. Lu
2018-12-07 17:17 ` Florian Weimer
2018-12-07 20:38 ` [PATCH] Don't use __typeof__ (getcpu) H.J. Lu
2018-12-07 20:49 ` Samuel Thibault
2018-12-07 22:18 ` H.J. Lu
2018-12-10 12:22 ` [PATCH] Add getcpu Szabolcs Nagy
2018-12-10 13:28 ` Florian Weimer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=alpine.DEB.2.21.1812052028140.12928@digraph.polyomino.org.uk \
--to=joseph@codesourcery.com \
--cc=carlos@redhat.com \
--cc=fweimer@redhat.com \
--cc=hjl.tools@gmail.com \
--cc=libc-alpha@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).