Re: Object Oriented PODs
* Sean M. Burke ([EMAIL PROTECTED]) [030221 01:20]: At 2/19/2003 01:46 PM +0100, Mark Overmeer wrote: [...]On this moment, I am owner of seven CPAN modules. The largest is Mail::Box, which has about 90 packages, each describing one class: it is object-oriented Perl. [...]Conclusion: POD is not sufficient to produce documentation for OO programs. What you say is undermined by one word: 90. NINETY! One of the surprising things about OOP as practiced in Perl land is that it you can typically do it perfectly well without deep or sprawling class hierarchies. Inheritance hierarchies is not a programming language dependent problem, but an programming style issue. Many Perl programmers have very little OO experience, and therefore think that simply using an @ISA turns an imparitive program into an OO version. You may think that 5 levels is too much, but it is not: it is the best way to avoid coding things double, and is not slow either, because of the method cache. Each level in the hierarchy has more than 5 (often complex) methods, so has its right of existence. While I want Pod to be as flexible as possible while still achieving its goals, the problem you point out is not very compelling, at least not as you've described it. I am always on the lookout for a solution to this problem; but for the time being, think of it as an inadvertent tax on ISA hierarchy deepness. I do not understand what this problem is in your case, and I see no inadvertent tax on ISA hierarchy deepness. What do you mean? Well, only the see you a use for yourself question of my e-mail is answered. Apparently not for your code. What remains is that I see a good use for myself (and many other OO modules). So the remaining questions I ask to the members of this POD discussion group remain: 2) If I extend my concept into a usable module, would the community accept it as alternative to plain POD? 3) What name-space should my module take? -- MarkOv %-] drs Mark A.C.J. OvermeerMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Object Oriented PODs
It was Friday, February 21, 2003 when Mark Overmeer took the soap box, saying: : Well, only the see you a use for yourself question of my e-mail is : answered. Apparently not for your code. What remains is that I see a : good use for myself (and many other OO modules). So the remaining : questions I ask to the members of this POD discussion group remain: : : 2) If I extend my concept into a usable module, would the community : accept it as alternative to plain POD? No. You do want an alternative to POD, but you won't find many people lining up to use it. Someone mentioned JavaDoc, that is a possibility here. Or something XML based, which describes your class and it's recursive OO hierarchy. This is most certainly a special case. Having written several deep class based libraries (not on the CPAN, but documented with POD), I have not found the need to extend POD. The 'SEE ALSO' standard section does well for me. I also put a description of base classes, and sometimes sub classes, in the 'ABSTRACT' section. : 3) What name-space should my module take? Sounds like you really want something in your own distribution, under tools/, bin/, or utils/. Something like, 'build_pod.pl'. Casey West -- If you don't double-click me, I can't do anything. -- John Aniston, on how computers have taken over his life
Re: Object Oriented PODs
* Casey West ([EMAIL PROTECTED]) [030221 14:11]: It was Friday, February 21, 2003 when Mark Overmeer took the soap box, saying: : Well, only the see you a use for yourself question of my e-mail is : answered. Apparently not for your code. What remains is that I see a : good use for myself (and many other OO modules). So the remaining : questions I ask to the members of this POD discussion group remain: : : 2) If I extend my concept into a usable module, would the community : accept it as alternative to plain POD? No. You do want an alternative to POD, but you won't find many people lining up to use it. Someone mentioned JavaDoc, that is a possibility here. Or something XML based, which describes your class and it's recursive OO hierarchy. I would really like you to take a look at the HTML which is produced, and then look back at this answer. No, you do not have to specify the hierarchy yourself, because that's easy to automatically detect when the documentation is constructed, at the moment that the distrubution is build. (The docs are visible at http://perl.overmeer.net/mailbox/html/) This is most certainly a special case. Having written several deep class based libraries (not on the CPAN, but documented with POD), I have not found the need to extend POD. The 'SEE ALSO' standard section does well for me. I also put a description of base classes, and sometimes sub classes, in the 'ABSTRACT' section. I think that is the main difference: CPAN. I nearly always know in which class I have to look, because I wrote the code. Other people who try to use your code usually have more problems finding the right class, certainly when they don't know the name of the method they need in the first place. : 3) What name-space should my module take? Sounds like you really want something in your own distribution, under tools/, bin/, or utils/. Something like, 'build_pod.pl'. Sorry, that's not the target of my original posting. I know how distributions are built (have made quite a few of them) I do not want to distribute the script with my package: I asked about providing this facility to other people documenting their OO modules. I spoke about the difference between logical en visible markup. With Perl6 coming up (in the not-to-near future), it might be useful to think about a POD6 as well. Perl6 will have nicer OO, so probably more OO programmers. POD is sufficient for small packages, but not for the some complex OO structures. -- MarkOv %-] drs Mark A.C.J. OvermeerMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Object Oriented PODs
Sean M. Burke [EMAIL PROTECTED] writes: What you say is undermined by one word: 90. Even with 2 classes it would be advanteous to have the PODs inherit just like the classes. -- Johan
Re: Object Oriented PODs
* Sean M. Burke ([EMAIL PROTECTED]) [030221 20:19]: I agree; but I can't quite picture a system that would do the right thing with around methods -- i.e., when a subclass do_whatever overrides do_whatever, but then calls SUPER::do_whatever. Oh, that's much simpler than you think. When a method in a higher level of the hierarchy overrules the lower, then the functionality is of the higher. The same for docs: the higher level doc overrules the lower. If have many cases where the higher level method does not need new docs (the docs of the method are inherited from the lower level because the implementation may be different but it works the same. I have also situations where the docs are overruled, but the code is not, for instance to indicate certain circumstances, problems, and such in that specific subclass. It works quite naturally. -- MarkOv %-] drs Mark A.C.J. OvermeerMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Object Oriented PODs
At 2/19/2003 01:46 PM +0100, Mark Overmeer wrote: What does bother me is that POD is visual markup instead of logical markup; the difference between HTML's I and EM, B and STRONG It is a common notion (which you may or may not be demonstrating here) that semanticity is binary: either a markup language is either semantic (logical) or visual. That is a fallacy. It is more accurate to say that a markup language can be semantic, or can be visual, with lots of grey areas inbetween. That too is a fallacy. A language can be entirely semantic, yet fail to express whole dimensions of that distinctions that you consider worth expressing. In any case, maybe it would help if I put into perlpodspec the =extend things I've been implementing in Pod::Simple, so that you can use them. I suppose it might help if you could define code for methodnames, arguments, etc. -- Sean M. Burke [EMAIL PROTECTED] http://search.cpan.org/~sburke/
Re: Object Oriented PODs
At 2/19/2003 01:46 PM +0100, Mark Overmeer wrote: [...]On this moment, I am owner of seven CPAN modules. The largest is Mail::Box, which has about 90 packages, each describing one class: it is object-oriented Perl. [...]Conclusion: POD is not sufficient to produce documentation for OO programs. What you say is undermined by one word: 90. NINETY! One of the surprising things about OOP as practiced in Perl land is that it you can typically do it perfectly well without deep or sprawling class hierarchies. While I want Pod to be as flexible as possible while still achieving its goals, the problem you point out is not very compelling, at least not as you've described it. I am always on the lookout for a solution to this problem; but for the time being, think of it as an inadvertent tax on ISA hierarchy deepness. -- Sean M. Burke [EMAIL PROTECTED] http://search.cpan.org/~sburke/
Re: Object Oriented PODs
On Thu, 20 Feb 2003 14:50:29 -0900, Sean M. Burke wrote: At 2/19/2003 01:46 PM +0100, Mark Overmeer wrote: What does bother me is that POD is visual markup instead of logical markup; the difference between HTML's I and EM, B and STRONG It is a common notion (which you may or may not be demonstrating here) that semanticity is binary: either a markup language is either semantic (logical) or visual. That is a fallacy. It is more accurate to say that a markup language can be semantic, or can be visual, with lots of grey areas inbetween. That too is a fallacy. A language can be entirely semantic, yet fail to express whole dimensions of that distinctions that you consider worth expressing. In any case, maybe it would help if I put into perlpodspec the =extend things I've been implementing in Pod::Simple, so that you can use them. I suppose it might help if you could define code for methodnames, arguments, etc. Smells like JavDoc to me. Not necessarily a bad thing. -- Sean M. Burke [EMAIL PROTECTED] http://search.cpan.org/~sburke/ -- Matthew O. Persico
