Re: Is your package Documented ?

From: 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

« previous php.pear.doc (#3407) next »