Re: may b a minor error
Re: may b a minor error
- Subject: Re: may b a minor error
- From: Terry Lambert <email@hidden>
- Date: Thu, 15 Jun 2006 20:01:23 -0700
On Jun 15, 2006, at 4:50 PM, Jeremy Pereira wrote:
On 15 Jun 2006, at 21:36, Terry Lambert wrote:
Correct.
All of the accessor/mutator functions applicable to uio structures
are fairly well documented in <sys/uio.h> itself.
I call BS on that.
A comment in the header like "uio_resid - return the residual IO
value for the given uio_t" is *not* "fairly well documented". It's
barely adequate given that you could deduce what the function does
from its name. The same applies to almost all of the functions
declared in that header.
I said "fairly well". I also referred you to the OpenDarwin source
code.
For "badly documented", I'd say it meant "comments do not match code",
which is not the case here.
For "well documented" (which I didn't claim), you'd need to have
attended or otherwise obtained the published materials from the last
WWDC, where a number of talks were given and labs were held. There
have also been a number of "Developer Kitchens" on various topics on
the Apple Campus, which tend to be multiday events concentrating on
specific technologies.
Great documentation would require that someone write a book (hint to
the more literate members of this list who are looking for a project).
...there's also those of us who are on this list, and try to help out
by voluntarily answering developer questions, but who have day jobs
working on code, and no ability to officially speak for Apple,
including but not limited to, commitments to work on documentation
instead of code, or ability to make forward looking statements. We
also can't disclose Apple confidential WWDC or "developer kitchen"
slides, talks, or reference materials.
I'm still waiting for the documentation for the VFS KPI more than a
year after it was introduced. Frankly, it's just not good enough.
Have you filed a bug report/feature request? As a lowly kernel
engineer, I'd have to say that an outside bug report is more likely to
get a block of time from an overworked technical writer than anything
I could personally say to anyone.
-- Terry
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Darwin-kernel mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden