Undocumented C functions
bruce.gray at acm.org
Sat Jun 5 19:47:27 UTC 2010
On Jun 5, 2010, at 1:42 PM, James E Keenan (kid51) wrote:
> we TODO those 25 files where we still have undocumented functions.
> I am willing to put some energy into writing documentation for these
> files, subject to a couple of provisos.
> 1. Since I'm not (professionally) a C programmer, I would need one
> or two code reviewers to read the documentation I write. Any
/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)
More information about the parrot-dev