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

timerfd() and system call review

Posted Aug 18, 2007 18:16 UTC (Sat) by landley (guest, #6789)
In reply to: timerfd() and system call review by mkerrisk
Parent article: timerfd() and system call review

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.

(Log in to post comments)

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