Parrot contributors,
When you run prove -v t/codingstd/pmc_docs.t (or make
nocritic_codetest), you see that there are 7 .pmc files with
undocumented functions -- a situation that has persisted for 2 to 3
years now! (See attachment.)
My hunch is that, with about two hours' effort spread among several
contributors, we could knock out all this documentation easily.
I further suspect that the best people to document these functions would
be the people who added them to the distribution in the first place! ;-)
But, in some cases, those people are no longer active contributors to
the project.
If desired, I could do a git blame on these seven files and send emails
to the people who appear to have written these PMCs in the first place.
But we would also need a fallback procedure for inactive contributors.
Can you discuss this at #parrotsketch this week and advise as to how we
should proceed?
Thank you very much.
Jim Keenan
t/codingstd/pmc_docs.t ..
1..107
ok 1 - src/dynpmc/dynlexpad.pmc
ok 2 - src/dynpmc/file.pmc
ok 3 - src/dynpmc/foo.pmc
ok 4 - src/dynpmc/foo2.pmc
ok 5 - src/dynpmc/gziphandle.pmc
ok 6 - src/dynpmc/os.pmc
ok 7 - src/dynpmc/pccmethod_test.pmc
ok 8 - src/dynpmc/rational.pmc
ok 9 - src/dynpmc/rotest.pmc
ok 10 - src/dynpmc/select.pmc
ok 11 - src/dynpmc/subproxy.pmc
ok 12 - src/pmc/addrregistry.pmc
ok 13 - src/pmc/alarm.pmc
ok 14 - src/pmc/arrayiterator.pmc
not ok 15 - src/pmc/bigint.pmc # TODO Missing function docs
# Failed (TODO) test 'src/pmc/bigint.pmc'
# at t/codingstd/pmc_docs.t line 92.
# src/pmc/bigint.pmc
# Boilerplate only:
# =item C<static BIGINT* bigint_get_self(PARROT_INTERP, PMC *self)>
#
# =item C<static char * bigint_get_string(PARROT_INTERP, PMC *self, int base)>
#
# =item C<static INTVAL bigint_cmp(PARROT_INTERP, PMC *self, PMC *value)>
#
# =item C<static INTVAL bigint_cmp_int(PARROT_INTERP, PMC *self, INTVAL value)>
#
# =item C<static double bigint_get_double(PARROT_INTERP, PMC *self)>
#
# =item C<static int bigint_get_bool(PARROT_INTERP, PMC *self)>
#
# =item C<static long bigint_get_long(PARROT_INTERP, PMC *self)>
#
# =item C<static void bigint_abs(PARROT_INTERP, PMC *self, PMC *dest)>
#
# =item C<static void bigint_add_bigint(PARROT_INTERP, PMC *self, PMC *value,
PMC
# *dest)>
#
# =item C<static void bigint_add_bigint_int(PARROT_INTERP, PMC *self, INTVAL
# value, PMC *dest)>
#
# =item C<static void bigint_check_divide_zero(PARROT_INTERP, PMC *value)>
#
# =item C<static void bigint_clear(PARROT_INTERP, PMC *self)>
#
# =item C<static void bigint_div_bigint(PARROT_INTERP, PMC *self, PMC *value,
PMC
# *dest)>
#
# =item C<static void bigint_div_bigint_int(PARROT_INTERP, PMC *self, INTVAL
# value, PMC *dest)>
#
# =item C<static void bigint_fdiv_bigint(PARROT_INTERP, PMC *self, PMC *value,
PMC
# *dest)>
#
# =item C<static void bigint_fdiv_bigint_int(PARROT_INTERP, PMC *self, INTVAL
# value, PMC *dest)>
#
# =item C<static void bigint_init(PARROT_INTERP, PMC *self)>
#
# =item C<static void bigint_mod_bigint(PARROT_INTERP, PMC *self, PMC *value,
PMC
# *dest)>
#
# =item C<static void bigint_mod_bigint_int(PARROT_INTERP, PMC *self, INTVAL
# value, PMC *dest)>
#
# =item C<static void bigint_mul_bigint(PARROT_INTERP, PMC *self, PMC *value,
PMC
# *dest)>
#
# =item C<static void bigint_mul_bigint_int(PARROT_INTERP, PMC *self, INTVAL
# value, PMC *dest)>
#
# =item C<static void bigint_neg(PARROT_INTERP, PMC *self, PMC *dest)>
#
# =item C<static void bigint_pow_bigint_int(PARROT_INTERP, PMC *self, INTVAL
# value, PMC *dest)>
#
# =item C<static void bigint_set(PARROT_INTERP, PMC *dest, PMC *src)>
#
# =item C<static void bigint_set_double(PARROT_INTERP, PMC *self, double value)>
#
# =item C<static void bigint_set_self(PARROT_INTERP, PMC *self, BIGINT *value)>
#
# =item C<static void bigint_set_str(PARROT_INTERP, PMC *self, const STRING
# *value, int base)>
#
# =item C<static void bigint_sub_bigint(PARROT_INTERP, PMC *self, PMC *value,
PMC
# *dest)>
#
# =item C<static void bigint_sub_bigint_int(PARROT_INTERP, PMC *self, INTVAL
# value, PMC *dest)>
#
# =item C<static void int_check_divide_zero(PARROT_INTERP, INTVAL value)>
#
ok 16 - src/pmc/bignum.pmc
ok 17 - src/pmc/boolean.pmc
ok 18 - src/pmc/bytebuffer.pmc
ok 19 - src/pmc/callback.pmc
not ok 20 - src/pmc/callcontext.pmc # TODO Missing function docs
# Failed (TODO) test 'src/pmc/callcontext.pmc'
# at t/codingstd/pmc_docs.t line 92.
# src/pmc/callcontext.pmc
# Boilerplate only:
# =item C<static Hash * get_hash(PARROT_INTERP, PMC *SELF)>
#
# =item C<static PMC * autobox_pmc(PARROT_INTERP, Pcc_cell *cell, INTVAL type)>
#
# =item C<static Pcc_cell* get_cell_at(PARROT_INTERP, PMC *self, INTVAL key)>
#
# =item C<static STRING * autobox_string(PARROT_INTERP, const Pcc_cell *cell)>
#
# =item C<static PMC * get_named_names(PARROT_INTERP, PMC *SELF)>
#
# =item C<static FLOATVAL autobox_floatval(PARROT_INTERP, const Pcc_cell *cell)>
#
# =item C<static INTVAL autobox_intval(PARROT_INTERP, const Pcc_cell *cell)>
#
# =item C<static void ensure_positionals_storage(PARROT_INTERP, PMC *self,
INTVAL
# size)>
#
# =item C<static void ensure_positionals_storage_ap(PARROT_INTERP, PMC *self,
# INTVAL size, INTVAL allocated_positionals)>
#
# =item C<static void mark_cell(PARROT_INTERP, Pcc_cell *c)>
#
# =item C<static void mark_hash(PARROT_INTERP, Hash *h)>
#
# =item C<static void mark_positionals(PARROT_INTERP, PMC *self)>
#
ok 21 - src/pmc/capture.pmc
not ok 22 - src/pmc/class.pmc # TODO Missing function docs
# Failed (TODO) test 'src/pmc/class.pmc'
# at t/codingstd/pmc_docs.t line 92.
# src/pmc/class.pmc
# Boilerplate only:
# =item C<static int cache_class_attribs(PARROT_INTERP, PMC *cur_class, PMC
# *attrib_index, PMC *cache, int cur_index)>
#
# =item C<static void initialize_parents(PARROT_INTERP, PMC *object, PMC
# *all_parents)>
#
# =item C<static void initialize_parents_pmc(PARROT_INTERP, PMC *object, PMC
# *all_parents, PMC *init)>
#
not ok 23 - src/pmc/complex.pmc # TODO Missing function docs
# Failed (TODO) test 'src/pmc/complex.pmc'
# at t/codingstd/pmc_docs.t line 92.
# src/pmc/complex.pmc
# Boilerplate only:
# =item C<static void complex_check_divide_zero(PARROT_INTERP, PMC *value)>
#
# =item C<static void float_check_divide_zero(PARROT_INTERP, FLOATVAL value)>
#
# =item C<static void int_check_divide_zero(PARROT_INTERP, INTVAL value)>
#
ok 24 - src/pmc/continuation.pmc
ok 25 - src/pmc/coroutine.pmc
ok 26 - src/pmc/default.pmc
ok 27 - src/pmc/env.pmc
not ok 28 - src/pmc/eval.pmc # TODO Missing function docs
# Failed (TODO) test 'src/pmc/eval.pmc'
# at t/codingstd/pmc_docs.t line 92.
# src/pmc/eval.pmc
# Boilerplate only:
# =item C<static PMC* get_sub(PARROT_INTERP, PMC *self, int idx)>
#
# =item C<static void mark_ct(PARROT_INTERP, PMC *self)>
#
ok 29 - src/pmc/eventhandler.pmc
ok 30 - src/pmc/exception.pmc
ok 31 - src/pmc/exceptionhandler.pmc
ok 32 - src/pmc/exporter.pmc
ok 33 - src/pmc/filehandle.pmc
ok 34 - src/pmc/fixedbooleanarray.pmc
ok 35 - src/pmc/fixedfloatarray.pmc
ok 36 - src/pmc/fixedintegerarray.pmc
ok 37 - src/pmc/fixedpmcarray.pmc
ok 38 - src/pmc/fixedstringarray.pmc
ok 39 - src/pmc/float.pmc
ok 40 - src/pmc/handle.pmc
ok 41 - src/pmc/hash.pmc
ok 42 - src/pmc/hashiterator.pmc
ok 43 - src/pmc/hashiteratorkey.pmc
ok 44 - src/pmc/imageiofreeze.pmc
ok 45 - src/pmc/imageiosize.pmc
ok 46 - src/pmc/imageiostrings.pmc
ok 47 - src/pmc/imageiothaw.pmc
ok 48 - src/pmc/imccompiler.pmc
ok 49 - src/pmc/integer.pmc
ok 50 - src/pmc/iterator.pmc
ok 51 - src/pmc/key.pmc
ok 52 - src/pmc/lexinfo.pmc
ok 53 - src/pmc/lexpad.pmc
ok 54 - src/pmc/managedstruct.pmc
ok 55 - src/pmc/mappedbytearray.pmc
ok 56 - src/pmc/multisub.pmc
not ok 57 - src/pmc/namespace.pmc # TODO Missing function docs
# Failed (TODO) test 'src/pmc/namespace.pmc'
# at t/codingstd/pmc_docs.t line 92.
# src/pmc/namespace.pmc
# Boilerplate only:
# =item C<static int maybe_add_sub_to_namespace(PARROT_INTERP, PMC *SELF, STRING
# *key, PMC *value)>
#
# =item C<static int ns_insert_sub_keyed_str(PARROT_INTERP, PMC *self, STRING
# *key, PMC *value)>
#
# =item C<static void add_multi_to_namespace(PARROT_INTERP, PMC *SELF, STRING
# *key, PMC *value)>
#
# =item C<static void add_native_to_namespace(PARROT_INTERP, PMC *SELF, STRING
# *key, PMC *value)>
#
# =item C<static void add_to_class(PARROT_INTERP, Parrot_NameSpace_attributes
# *nsinfo, PMC *classobj, STRING *key, PMC *value)>
#
ok 58 - src/pmc/nativepccmethod.pmc
ok 59 - src/pmc/nci.pmc
ok 60 - src/pmc/null.pmc
not ok 61 - src/pmc/object.pmc # TODO Missing function docs
# Failed (TODO) test 'src/pmc/object.pmc'
# at t/codingstd/pmc_docs.t line 92.
# src/pmc/object.pmc
# Boilerplate only:
# =item C<static PMC * find_cached(PARROT_INTERP, PMC *_class, STRING *name)>
#
# =item C<static INTVAL get_attrib_index(PARROT_INTERP, PMC *self, STRING
*name)>
#
# =item C<static void cache_method(PARROT_INTERP, PMC *_class, STRING *name, PMC
# *method)>
#
ok 62 - src/pmc/opcode.pmc
ok 63 - src/pmc/oplib.pmc
ok 64 - src/pmc/orderedhash.pmc
ok 65 - src/pmc/orderedhashiterator.pmc
ok 66 - src/pmc/packfile.pmc
ok 67 - src/pmc/packfileannotation.pmc
ok 68 - src/pmc/packfileannotations.pmc
ok 69 - src/pmc/packfilebytecodesegment.pmc
ok 70 - src/pmc/packfileconstanttable.pmc
ok 71 - src/pmc/packfiledebug.pmc
ok 72 - src/pmc/packfiledirectory.pmc
ok 73 - src/pmc/packfileopmap.pmc
ok 74 - src/pmc/packfilerawsegment.pmc
ok 75 - src/pmc/packfilesegment.pmc
ok 76 - src/pmc/packfileview.pmc
ok 77 - src/pmc/parrotinterpreter.pmc
ok 78 - src/pmc/parrotlibrary.pmc
ok 79 - src/pmc/pmclist.pmc
ok 80 - src/pmc/pmcproxy.pmc
ok 81 - src/pmc/pointer.pmc
ok 82 - src/pmc/ptr.pmc
ok 83 - src/pmc/ptrbuf.pmc
ok 84 - src/pmc/ptrobj.pmc
ok 85 - src/pmc/resizablebooleanarray.pmc
ok 86 - src/pmc/resizablefloatarray.pmc
ok 87 - src/pmc/resizableintegerarray.pmc
ok 88 - src/pmc/resizablepmcarray.pmc
ok 89 - src/pmc/resizablestringarray.pmc
ok 90 - src/pmc/role.pmc
ok 91 - src/pmc/scalar.pmc
ok 92 - src/pmc/scheduler.pmc
ok 93 - src/pmc/schedulermessage.pmc
ok 94 - src/pmc/sockaddr.pmc
ok 95 - src/pmc/socket.pmc
ok 96 - src/pmc/string.pmc
ok 97 - src/pmc/stringbuilder.pmc
ok 98 - src/pmc/stringhandle.pmc
ok 99 - src/pmc/stringiterator.pmc
ok 100 - src/pmc/structview.pmc
ok 101 - src/pmc/sub.pmc
ok 102 - src/pmc/task.pmc
ok 103 - src/pmc/timer.pmc
ok 104 - src/pmc/undef.pmc
ok 105 - src/pmc/unmanagedstruct.pmc
ok 106 - t/tools/dev/headerizer/testlib/fixedbooleanarray_pmc.in
ok 107 - t/tools/dev/headerizer/testlib/nci_pmc.in
ok
All tests successful.
Files=1, Tests=107, 0 wallclock secs ( 0.04 usr 0.00 sys + 0.31 cusr 0.01
csys = 0.36 CPU)
Result: PASS
_______________________________________________
http://lists.parrot.org/mailman/listinfo/parrot-dev
