[wp-docs] Structure of documentation

[Mark Styles]

On Thu, Feb 22, 2007 at 05:29:03AM -0800, Jennifer Hodgdon wrote:
> >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. 
 
> 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.

Documentation can be generated from code even without the doc comments.
It would be useful to have pages auto-generated for every function as it
would at least give a starting point for documenters to add to.

There may be functions that the developers prefer to be less visible and
undocumented, but these can be removed after the auto-generation.

I could generate a bunch of function based docs quite easily, but I have
no idea how to wiki-ize them.

> c) You do not necessarily get good documentation from developers.

Very true, but you do get an accurate starting point from which the 
"professional" documentors can embellish and refine.

As an aside, why is the codex search facility so bad? And why doesn't it
search the function reference pages?

-- 
Mark 
http://www.lambic.co.uk

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://comox.textdrive.com/pipermail/wp-docs/attachments/20070222/e552f014/attachment.pgp