timerfd() and system call review [LWN.net]

timerfd() and system call review

Posted Aug 14, 2007 18:30 UTC (Tue) by mhelsley (subscriber, #11324)
Parent article: timerfd() and system call review

"one of the best ways to find shortcomings in an API is to attempt to document it comprehensively"

True. However it's not nearly as good when the person involved in writing the code implementing the API also writes the documentation -- that does not strain underlying assumptions in the way that thorough review and proper documentation processes tend to.

So perhaps once the API is in glibc and documented by another party it could be considered "stable".

(Log in to post comments)

timerfd() and system call review

Posted Aug 15, 2007 1:24 UTC (Wed) by mkerrisk (subscriber, #1978) [Link]

"one of the best ways to find shortcomings in an API is to attempt to document it comprehensively"

Agreed. However, I've been trying to encourage kernel developers to supply the beginnings of a man page that I then review. Even that is a very fruitful process, when it happens. But the ideal is of course as you suggest a much better review and documentation process involving kernel developers.

So perhaps once the API is in glibc and documented by another party it could be considered "stable".

There are many problems with this idea: some APIs never make it to glibc; sometimes glibc provides a wrapper that modifies the API; sometimes documentation does not arrive for a very long time...

timerfd() and system call review

Posted Aug 18, 2007 18:16 UTC (Sat) by landley (guest, #6789) [Link]

Two points:

1) Before a third party can document an API, they have to learn how to
use it, which is a chicken and egg problem (especially if you're trying
to be thorough). If nothing else it's insanely time consuming.

2) I don't pay much attention to glibc, I pay attention to uClibc. I'll
happily document what uClibc implements, and ignore the rest because if
uClibc doesn't implement it, it really can't be all that important.

timerfd() and system call review

Posted Aug 19, 2007 7:09 UTC (Sun) by mkerrisk (subscriber, #1978) [Link]

1) Before a third party can document an API, they have to learn how to use it, which is a chicken and egg problem (especially if you're trying to be thorough). If nothing else it's insanely time consuming.

Doing it that way would be. Obviously efficiently written documentation needs to be collaborative, either written by the developer, and improved via critique from peers and/or individuals well versed in writing documentation, or written by a third party with help from the developer, who explains the API.

timerfd() and system call review

Posted Aug 20, 2007 5:20 UTC (Mon) by landley (guest, #6789) [Link]

You didn't follow the saga of my attempts to document the subset of sysfs
used to populate /dev. Responses I got included:

A) Contradictory information from different developers.
B) Corrections consisting of "that's wrong" with no hint about the
approved way to do it.
C) Being repeatedly told I was an idiot and not worth their time.
D) Questioning why anyone would want to document this when someone's
already written a program using it.
E) Being repeatedly told "there is no stable API", I.E. outright
resistance to documenting this area because they didn't want to lose the
freedom to change it on a whim.

I also got some useful information, but both of the developers I need to
talk to are essentially spam-blocking me now. Oh well.

Also, although development and debugging parallelize just fine, editorial
functions don't. This is why you generally don't have multiple
maintainers whose jurisdictions overlap unless there's a clear hierarchy
of who reports to who. Writing documentation to be read by end users has
a significant editorial function.

Rob

timerfd() and system call review

Posted Aug 15, 2007 15:18 UTC (Wed) by dougg (subscriber, #1894) [Link]

In the 9 years that I have designed, implemented, supported and documented one particular kernel API not one of the thousands of emails that I have received concerning that API was an offer to write documentation.

I did notice that the glibc folks removed some documentation from the header file that defines the API. I'm not aware that they put that documentation anywhere else. And someone recently noted the discrepancy between the glibc distributed header and the kernel driver header. The solution proposed was to remove the documentation from the driver header as well.

Now I get to sit back and watch someone else go through a similar process with the bsg driver. And that driver is going to be released with an API that has pending changes (at least 6 months old) held up due to kernel bureaucracy.