[wp-docs] Structure of documentation

[Martin Sturm]

2007/2/21, Jennifer Hodgdon <yahgrp at poplarware.com>:
> There was a reference page before, but it was missing about 75% of the
> functions. Jump in and add documentation and organization at will!
> Please! :) You also mentioned some kind of Table of Contents -- the
> Wiki makes it easy to add links down the page, so that can be added
> too. Good idea!

Last night, I was wondering why the function reference is generated
from the source? I saw somewhere some guidelines on in-code
documentation, but apparently, this is not used to create
documentation. I am also a Java developer, and have some experience
with JavaDoc. In the past I used PHPDoc (or PHPDocumenter or
something, I'm not sure about that) and that was similar to JavaDoc. I
think it is possible to create JavaDoc-like documentation in the
WordPress source, and generate (at least a large part of) the function
reference. It has multiple benefits:
1) Function definition and parameters doesn't have to be copy/paste
(reducing errors)
2) It is easier for developers to keep the documentation up-to-date,
because it can be done at the same place where the actual change in
code is done.
3) The source code is documented properly (I haven't investigate this
thoroughly, but some quick checks seems to suggest that there is not
much documentation in the source code.

I realize that creating function reference this way, takes some work,
but one the long take, maintaining the function reference is much
easier.

--
Martin