Undocumented C functions

[Bruce Gray]

On Jun 5, 2010, at 1:42 PM, James E Keenan (kid51) wrote:
--snip--
> we TODO those 25 files where we still have undocumented functions.
--snip--
> I am willing to put some energy into writing documentation for these  
> files, subject to a couple of provisos.

kid51++

> 1. Since I'm not (professionally) a C programmer, I would need one  
> or two code reviewers to read the documentation I write.  Any  
> volunteers?

/me raises a rusty hand.
Parrot is the only C that I have done in the last 7 years, but I was  
paid for C in my early career.
I will compare your text to the code being documented, for those  
functions that I clearly understand.

> 2. To the extent that the undocumented functions are little more  
> than Parrot wrappers around standard C library functions,
> it makes sense to quote from existing man pages.

Perhaps it does *not* make sense. For example:
Function dlsym() in config/gen/platform/generic/dl.c needs docs.
Compare `man 3 dlsym` and http://linux.die.net/man/3/dlsym to  
dlsym()'s docs in config/gen/platform/win32/dl.c.

The doc in win32/dl.c is more useful because it is couched in terms of  
the wrapper's API, and how to use it in Parrot.
The implementation details are better left out of the POD, and placed  
in true C-comments (or let the code speak for itself).

That said, reading all of the manpage versions you can access should  
make clearer which details are platform-specific, and which are the  
"essence* of the C-library function.
That should also reduce copyright issues, on which I am under- 
qualified to comment.

-- 
Hope this helps,
Bruce Gray (Util)