[wp-docs] Structure of documentation

[Carthik Sharma]

On 2/22/07, Martin Sturm <msturm10 at gmail.com> wrote:
> 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).
>

We have discussed this twice (or thrice) before, on this list and on
the wp-hackers list. Please peruse those old threads to see why this
idea was not implemented.

Thank you for your suggestions :) Good to see action on this list again!

Carthik.
> --
> Martin
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
>


-- 
Ph.D. Candidate
University of Central Florida
Homepage: http://carthik.net