Last night, I was wondering why the function reference is [not] generated
from the source [like Javadoc]? I saw somewhere some guidelines on in-code
documentation, but apparently, this is not used to create
documentation.
I believe this has been suggested before. The benefits you cited are
clear, but given the current state of affairs, I can think of a couple
of counter-arguments:
a) Currently, very few of the functions in WordPress have any
documentation in the code, much less properly formatted xxDoc
comments, while many functions (especially the "Template Tags") have
Codex pages.
b) Anyone can edit the Codex to contribute documentation, and it will
be up on the site immediately. Adding documentation to the code (or
fixing it) requires submitting a patch and waiting for a new version
of WordPress to come out, assuming the patch is accepted. Plus, the
special documentation comment might not be well-formed enough to
generate the documentation, which would then require a new patch and
another release cycle before it is up on the Codex.
c) You do not necessarily get good documentation from developers.
--Jennifer
--
Jennifer Hodgdon
Poplar ProductivityWare * www.poplarware.com
Web Databases/Scripts * Modeling/Analysis/Palm OS Software
_______________________________________________
wp-docs mailing list
[email protected]
http://lists.automattic.com/mailman/listinfo/wp-docs
