Undocumented C functions

James E Keenan jkeen at verizon.net
Sat Jun 5 18:42:22 UTC 2010


When we prepare a release, the release manager has to fun 'make 
fulltest', one part of which is 'make codetest' -- the target which 
measures compliance with our coding standards.  Among the tests run in 
'codetest' is t/codingstd/c_function_docs.t, which, as its name implies, 
reports on the presence of documentation for all functions in C source 
code (.c) files.  c_function_docs.t always PASSes, but that's only 
because we TODO those 25 files where we still have undocumented functions.

prove -v t/codingstd/c_function_docs.t | grep 'not ok'
not ok 2 - config/gen/platform/darwin/memalign.c # TODO Missing function 
docs
not ok 13 - compilers/imcc/parser_util.c # TODO Missing function docs
not ok 14 - compilers/imcc/pbc.c # TODO Missing function docs
not ok 15 - compilers/imcc/pcc.c # TODO Missing function docs
not ok 16 - compilers/imcc/reg_alloc.c # TODO Missing function docs
not ok 18 - compilers/imcc/symreg.c # TODO Missing function docs
not ok 21 - compilers/pirc/src/pircapi.c # TODO Missing function docs
not ok 30 - config/gen/platform/ansi/dl.c # TODO Missing function docs
not ok 31 - config/gen/platform/ansi/exec.c # TODO Missing function docs
not ok 32 - config/gen/platform/ansi/time.c # TODO Missing function docs
not ok 35 - config/gen/platform/generic/dl.c # TODO Missing function docs
not ok 37 - config/gen/platform/generic/exec.c # TODO Missing function docs
not ok 40 - config/gen/platform/generic/math.c # TODO Missing function docs
not ok 41 - config/gen/platform/generic/memalign.c # TODO Missing 
function docs
not ok 44 - config/gen/platform/generic/stat.c # TODO Missing function docs
not ok 45 - config/gen/platform/generic/time.c # TODO Missing function docs
not ok 46 - config/gen/platform/netbsd/math.c # TODO Missing function docs
not ok 48 - config/gen/platform/openbsd/math.c # TODO Missing function docs
not ok 50 - config/gen/platform/solaris/math.c # TODO Missing function docs
not ok 51 - config/gen/platform/solaris/time.c # TODO Missing function docs
not ok 66 - examples/compilers/japhc.c # TODO Missing function docs
not ok 136 - src/string/charset/ascii.c # TODO Missing function docs
not ok 137 - src/string/charset/binary.c # TODO Missing function docs
not ok 138 - src/string/charset/iso-8859-1.c # TODO Missing function docs
not ok 140 - src/string/charset/unicode.c # TODO Missing function docs

The facts that we have only 25 TODO-ed files left and that many of them 
are relatively simple C files under config/gen/platform/ is an 
indication that getting this test to pass without TODOs is actually 
achievable.

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 volunteers?

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.  Do we have a preference as to which man 
pages we quote from or use as guidance?  (I have immediate access to 
Linux and Darwin man pages, and via Darwin indirect access to FreeBSD.) 
  And are there any licensing/copyright issues to be considered here?

Thank you very much.
kid51



More information about the parrot-dev mailing list