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
_______________________________________________
http://lists.parrot.org/mailman/listinfo/parrot-dev
