On Wed, Dec 5, 2018 at 12:43 PM Joseph Myers <joseph@codesourcery.com> wrote:
>
> 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.

I added an entry to manual/process.texi.

> (The NEWS entry also needs to state that this function is Linux-specific.)
>

Fixed.

Here is the updated patch.

-- 
H.J.