Re: Date_Span and some initial observations

On Tue, 2003-09-09 at 06:02, Greg Beaver wrote: > Samuel Ziegler wrote: > > > By accessibility of documentation I mean that there is lots of good > > documentation, but it's not very easy to get at, IMHO. I tried to setup > > PHPDocumentor, but ended up with a web interface with so many options, I > > didn't know where to begin. I find myself digging through the source > > reading the comments just because I don't have the time to learn how to > > set up the document generation program. IMHO, the docs should be > > available immediately after the install command returns. The fact that > > CPAN modules have man pages installed and ready to go after install is a > > great example of this. > > You would benefit from knowing the documentation for phpDocumentor is at > http://www.phpdoc.org - this is also noted in the web > interface, but I'm > sure you just missed it. The PEAR manual is designed in such a way, it > makes no sense to document applications at pear.php.net. Perhaps this > will change in the next year. I actually did start looking through the phpdoc.org website, but being a busy person, it was just quicker for me to look at the source than figure out how to use the documentation generation program. I have used several of these in the past (JavaDoc, doxygen, etc...) and don't have a strong desire to learn another one. My question is, why make the user of the packages responsible for generating these docs? Why not either: 1. Have the packager generate the documentation before posting the module. or 2. Have pear auto-generate the documentation after install. IMHO, the latter seems slightly more useful for the PEAR project. I'd be willing to code it up if people like the idea. Again, my issue wasn't the use of phpDocumentor to generate documentation, it's the fact that the burden is on the user to generate said documentation. Thanks! - Sam