Re: PHPod documentation

Jon Parise wrote: > > On Tue, Jul 31, 2001 at 02:44:16PM +0200, Stig S. Bakken wrote: > > > But these two systems have slightly different markup syntaxes, JavaDoc > > has metadata markup, while POD has formatting markup. What about > > combining the two into PHPod: > > > > we could easily document function parameters etc. with a POD-like format > > too, and and a bonus we would not inherit all the features from JavaDoc > > that don't really fit too well with PHP, but we can define a format that > > is perfect for PHP. What about this: > > Hmm... I'm not sure which idea I like best here, considering all > of the ramifications of each. > > 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. > > 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). This is along the lines I'm thinking myself. I don't really want to throw away PHPDoc, but we do need some more formatting support than we currently have. Looking back now I understand that Tomas and Chuck jumped a bit in their chairs, I came out a lot more like a dog with rabies than I meant to. :-) The point is that right now we don't have any formatting possibilities in PHPDoc. Some places people ues <code> and other HTML tags because JavaDoc seems to allow some HTML, but that's not really for us since PHP's documentation system is not HTML-centric. We've discussed this before (a year or more ago I think), but never really ended up with any solution. DocBook markup in comments is right out of the question. So the issue has been on hold for a while, and when Graeme posted his suggestion about (using|stealing ideas from) POD I got this "why didn't we think of that last year" kind of feeling. POD deals with formatting in a simple way (this is where the no-nonsense comes in :-): you have a few simple tags (=head1, =item C<blah> etc.) that provide 80% of the formatting you need, and that are easy to convert to any other format. I'm looking forward to having a working PHPDoc processor (a Zend execution mode that outputs "tokens" would be a perfect starting point) , but I do think we should really think about we want to do with the format, and get rid of the "Java-isms" that don't fit with PHP. - Stig