[wp-docs] Structure of documentation

[Jennifer Hodgdon]

> 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