[wp-docs] Structure of documentation

[Martin Sturm]

2007/2/22, Jennifer Hodgdon <yahgrp at poplarware.com>:
> I want to make it clear that I am a developer, and I think the idea of
> having the functions documented in the code is the Right Thing To Do.
>
> I also want to make it clear that I am not a decision maker in
> WordPress, just an Interested Participant.
>
> So... I was thinking about this idea of having the WordPress PHP code
> being the source for Codex function documentation pages from a
> practical perspective, and I do not think it is practical right now...
> or at least, here are the practical concerns that I would want to see
> addressed in a reliable, workable way, before such a plan was implemented:

I'm not sure if it is desirable to use the php source of Wordpress as
to one and only documentation source for the reference. Maybe I didn't
make this clear enough in my previous posts.
Because of the nature of the Codex (a wiki, which means that everybody
can modify it at will) it would be almost impossible (I guess) to keep
the source code documentation and the Wiki-reference documentation in
sync.

> * Figure out standards for function headers that would translate to
> good function documentation pages, and find or write code to extract
> all the function documentation and put it into the Codex (or another
> web site).

I don't think it is very smart to invent such a format again. As I
mentioned before, there is already the JavaDoc/PHPDocumenter format,
which is widely used and considered as a standard for this.

I did some experimentation this afternoon, and discovered it is pretty
easy to generate 'templates' for the function reference using
PHPDocumentor (http://www.phpdoc.org) which can be directly used on
the Codex. By default PHPDoc generates HTML documentation, but with
little effort it is possible to write a 'Convertor' for this package,
which format the documentation in MediaWiki-tags. I have already a
Convertor which makes a templatedocumentation for functions, including
the functionname, parameters, default values for parameters, return
value and so on. When there is a so-called DocBlock (i.e. comments in
JavaDoc format) this is automatically included in the template.

--
Martin Sturm