[wp-docs] Structure of documentation

[Martin Sturm]

2007/2/22, Jennifer Hodgdon <yahgrp at poplarware.com>:
> 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.

I'm aware of this argument (and was expecting it), and it is certainly
true. But, it doesn't require a release to generate new documentation
(I suppose). It may even be possible to create a seperate branch and
add the documentation to it. I suspect that the most important API
functions will not change very much every release (because that would
break plugins and templates).

As Mark Styles suggests, generating the documentation from the source
doesn't mean you have a 'complete' documentation at once. Most
implementations of document generators also work when there is no
specific formatted comments in the source code, but generate 'document
templates' containing the name of the function, its arguments and
(maybe) the return value. Also is it possible (in the case of
objects/classes) to automatically add links to parent classes.
This generated documentation could form a starting point for most of
the functions (there are a lot functions not documented currently, as
you pointed out).

I have to point out that it is just a new idea I had, and I haven't
worked it out entirely, but I suspect that, if we want it, it is
possible to realise this. I think it will improve also make it easier
to improve the quality of code (some files of the Wordpress source
contain pretty bad code) because maintaining the documentation
enforced developers to think about their changes.

> 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.

If the documentation in the source is enforced (just like the 'coding
style guidelines'), it will be possible to keep this up-to-date (other
open source projects are doing it as well, why would it be impossible
in this project?). I understand that it require some effort. I suspect
it is possible to give someone who is coordinator of this project, can
be given rights to commit the documentation to the source, or at least
manage the patches in trac (and pass them to the person who can commit
them in a 'ready' way). Again, I don't think it is only possible to
update the documentation when a release is happening. It would be
stupid to only update the reference documentation when there is a
release.

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

True, but some developers can write good documentation (or at least
update it). Maybe I'm not clear at this point, but I think the initial
source documentation should be written by a documenter. I don't expect
the current developers creating this documentation.

One think that could be a 'problem' is how we can generate
documentation in a format which can be put on the Codex. This morning,
I looked at PHPdocumentor (a Pear project) and I think it is possible
to use this package to generate documentation which can be put on the
Codex (which is just a wiki as far as I understand). The PHP
documentation is also generated from the sourcecode documentation (as
far as I understand).

--
Martin