Re: PHPod documentation

Chuck Hagenbuch wrote: > > Quoting Jon Parise <jon@php.net>: > > > I'm sort of leaning toward developing our own PearDoc system that > > is based on the existing PHPDoc / JavaDoc syntax (because of > > legacy code and familiarity), but I would really like to see the > > capabilities of POD-style documentation be added, too. > > For those of us who've never used POD, maybe if someone were to explain what > those (the capabilities of POD-style documentation) are, it would help? POD stands for "Plain Old Documentation" and is an embedded documentation format used by Perl. For examples, look at any .pm file in /usr/lib/perl5/site_perl. POD is very plain text-centric, but that doesn't mean we can steal the ideas and use them in a different way. > > So I think the thing to do is create a PearDoc standard that is a > > superset of JavaDoc (while ignoring some of the irrelevant tags) > > and includes the most helpful features of POD (but not > > necessarily the POS syntax itself). > > I'm going to bump investigating the current phpdoc tools (people have been > mentioning phpDocumentor(?) as being good?) and setting something up on the > PEAR site to display docs of all of the classes to near the top of my > priorities. We can go from there? If you can get a cron job up, that's a great start. But we should revise the PHPDoc format asap. I'm too tired to make meaningful suggestions now though, I'll get back to that tomorrow. - Stig