Undocumented C functions

Will Coleda will at coleda.com
Sat Jun 5 19:38:40 UTC 2010


On Sat, Jun 5, 2010 at 2:42 PM, James E Keenan <jkeen at verizon.net> wrote:
> 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?

My 2¢: If they're just wrappers, I would just say that rather than
copying docs from elsewhere.

> Thank you very much.
> kid51
>
> _______________________________________________
> http://lists.parrot.org/mailman/listinfo/parrot-dev
>



-- 
Will "Coke" Coleda


More information about the parrot-dev mailing list