#1726: Missing POD in .pmc files (and a couple of others)
------------------------------+---------------------------------------------
Reporter: mikehh | Owner: jkeenan
Type: todo | Status: assigned
Priority: normal | Milestone:
Component: coding_standards | Version: trunk
Severity: medium | Keywords:
Lang: | Patch: applied
Platform: |
------------------------------+---------------------------------------------
Comment(by jkeenan):
This ticket has been effectively stalled for two-and-a-half months. The
approach taken by mikehh and me in our work on the ticket met strong
opposition in #parrotsketch on August 17. I am attaching an extract of
that discussion to this ticket.
I am also attaching an extract from ''docs/pdds/pdd07_codingstd.pod'' that
is relevant to this discussion. Whatever we do in this area has to be
governed by the PDD. The PDD calls for ''inline Pod documentation
containing information on the implementation decisions.'' It goes on to
prescribe a format for POD inside of C-style comments for ''[e]very non-
local named entity, be it a function, variable, structure, macro or
whatever.'' So it seems that our current policy leans in favor of
documentation in POD format for C functions.
If you disagree with this policy, then a patch to revise
''pdds/pdd07_codingstd.pod'' needs to be proposed. And we will need
patches for ''t/codingstd/c_function_docs.t'' and
''t/codingstd/pmc_docs.t'' that reflect the policy and report accurately
on what remains to be documented.
Thank you very much.
kid51
--
Ticket URL: <https://trac.parrot.org/parrot/ticket/1726#comment:12>
Parrot <https://trac.parrot.org/parrot/>
Parrot Development
_______________________________________________
parrot-tickets mailing list
[email protected]
http://lists.parrot.org/mailman/listinfo/parrot-tickets
