Re: Is your package Documented ?
| From: | Klaus Guenther | Date: | Wed, 14 Apr 2004 07:04:24 +0000 |
| Subject: | Re: Is your package Documented ? | ||
| References: | 1 | Groups: | php.pear.doc |
| Request: | Send a blank email to pear-doc+get-3407@lists.php.net to get a copy of this message | ||
From: "David Costa" <gurugeek@php.net>
> Is you package documented and listed in the pear manual ?
>
> If the answer to this question is No, please let us know
> why not ;) (email the Doc list at pear-doc@lists.php.net)
>
> You have documentation on your personal site in a different format ?
> let us know!
>
> Extensive documentation (whenever possible with clear, "for dummies"
> examples) is critical to ensure both your package and PEAR
> success among users.
>
> Documentation can be automatically-generated using PHPDocumentor
> http://pear.php.net/package/PhpDocumentor/
I have relatively decent documentation in phpdoc format for both of my
packages. One is pre-1.0, so I'm not sure it makes sense for me to document
it, as the api may change at any time (HTML_CSS). The other, HTML_Page2, is
relatively stable (I prematurely release released it as an HTML_Page RC, but
plan on still making some minor changes). I can generate the HTML docs
easily, and yes, I do have a bunch of examples in there. I will be adding
examples for each method, of course.
However, I'm rather unsure of whether phpDocumentor will output proper
peardoc2. Therefore, I've not committed it yet. It's also available nowhere
on the web... yet.
The other thing that's really bugging me is that Greg burst the tutorial
bubble. One of the best features of phpDocumentor is that you can make
tutorials. And you should write them in special docbook, which will get
automatically get converted to your desired output. But now he says that no,
it's not peardoc compatible. Nothing against him or phpDocumentor: it's a
wonderful tool. But if it's going to be useful to pear documentors, please,
please fix the tutorial issue. Or at least demonstrate how to write a
tutorial that renders to valid peardoc2 :-)
And... tutorials should be able to include graphics, as well... so that's
something that needs to be available in whatever finally becomes the pear
documentation standard... Not saying that docbook is necessarily the wrong t
hing, but we need certain things that peardoc2 currently does not offer.
Klaus