Ticket #1726: excerpts.parrotsketch.20100817.txt

Time  Nick           Message
00:43 kid51          * 1. There was discussion on #parrot as to the desirability of writing documentation *in POD format* for *static* functions in the .pmc files (TT #1726).  It was argued that such functions should be documented merely by inline comments on the grounds that they are "implementation details."
00:43 kid51          ** I disagree.  If *all* our functions were documented in *all* our source code files, we could have the luxury of deciding which functions should go into POD and which can be relegated to inline comments.  But we are so far away from that that I believe we should err on the side of getting all functions documented in POD format, which is the only format for which we have (somewhat) good tools to detect the presence of
00:43 kid51          documentation.  The overwhelming majority of static functions in the TT #1726 files lacked comments as well as POD up until last week.
00:44 kid51          ** Another case where the perfect is the enemy of the good.
...
21:38 chromatic      Given the beneficial desire to document all C functions but the meh of adding public POD to static functions, any thoughts on changing the "Does this have documentation?" test to accept mere C comments for static functions instead of full POD?
21:38 cotto_work     +1
21:38 Paul_the_Greek +1
21:39 plobsing_work  +1
21:39 darbelo        +1
21:39 cotto_work     (unless it means more boilerplate comments to pass the test instead of documenting the functions)
21:39 Util           I thought someone (kid51?) had made huge progress in cleaning up the backlog of un-PODed C functions
21:39 chromatic      Any objections?
21:39 mikehh         if you can come up with a reliable test that does that, at least with the pod headers we can determine that there is documentation there
21:40 mikehh         or would just any comment in the function do? I do't realy think so
21:40 mikehh         don't
21:40 chromatic      My concern with requiring POD is that these are functions not for public consumption and thus should not be in public documentation.
21:41 NotFound       A way to extract and put elsewhere all public api functions, methods and vtables will be better, IMO.
21:41 Paul_the_Greek Which prevents users from relying on some internal feature.
21:41 mikehh         who are we documenting for, I think we document for devs as much as users
21:41 NotFound       Its PODs, I mean.
21:41 tcurtis        Is there any way to make it so that we have POD for both (because POD seems to be easier to check for), but the non-public functions are marked so that they don't show up in public docs?
21:41 plobsing_work  I think one multi-line descriptive comment above static functions is appropriate
21:41 chromatic      Figuring out how to hide POD seems like more work to me, but if someone can figure it out that's fine too.
21:41 Paul_the_Greek As a new developer, I don't see why I'd want static functions documented externally.
21:42 tcurtis        Although, if so, that should probably wait until html_cleanup gets merged, perhaps.
21:42 chromatic      Do we have some sort of conclusion as to what we should do?
21:42 mikehh         I agree, but from the developer point of view, we definately *need* documentation
21:43 Paul_the_Greek Require a comment preceding a static function, but not a POD. Hide static PODs.
21:43 chromatic      I can take a look at fixing the test if we agree on doing so.
21:44 mikehh         as long as we have a way of requiring comments for every static function
21:44 Paul_the_Greek Any requirements for data structures?
21:44 chromatic      We haven't reached that yet.
21:44 mikehh         we should probably go for that too
21:45 Paul_the_Greek At least as important, I think.
21:45 cotto_work     no requirements, but more comment patches are welcome
21:45 cotto_work     (yet)