Re: [PATCH] Add getcpu

[Joseph Myers <joseph at codesourcery dot 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