2007/2/22, Jennifer Hodgdon <[EMAIL PROTECTED]>:
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
_______________________________________________
wp-docs mailing list
[email protected]
http://lists.automattic.com/mailman/listinfo/wp-docs
