I am not sure why, but this post reminded me of an important aspect I forgot to mention. P5EE documentation must survive/live outside of the modules. This means I will need to use/create tools to move the pod out of existing modules that use embedded documentation.
I say this possibly out of limited analysis of the problem/goal at hand, but in order to provide documentation revisions back to the module owners they will need to edit the P5EE 'certified' documentation outside of the module. I am not however suggesting that pod style comments inside of a module should be avoided, but just stating the possible difficulty in keeping things in sync between the 'certifier' and the developer if they are separate (multiple) people. Additionally it will be optional for developers to "Believe" in P5EE so we need to not force compliance/inclusion of our modified documentation. It is however hoped that developers will like respect the P5EE stamp of approval as it evolves. In the interim the P5EE approved modules along with the P5EE documentation can live independent of the authors creation. Aaron On Thu, 2002-08-01 at 16:11, Stephen Adkins wrote: > Hi, > > At 03:35 AM 8/1/2002 -0500, Nigel Hamilton wrote: > ... > > I noticed that the p5ee::Blue pages have javadoc-esque > >documentation - for me this is a great leap forward to combining > >individual CPAN modules into cohesive packages. > > Hi, > > You have seen the documentation I produce for P5EEx::Blue > > http://www.officevision.com/pub/p5ee/software/htdocs/api/ > > package using the "perldocs" utility > > http://www.officevision.com/pub/p5ee/software/sbin/perldocs > http://cvs.perl.org/cvsweb/p5ee/P5EEx/Blue/sbin/perldocs.PL > > which is not at all finished or cleanly coded (but the output > looks nice). > > My intent (when I get back around to it) is to write a more general- > purpose version of perldocs which creates this kind of documentation > for whatever you have installed on your system (i.e. from CPAN or > wherever). Its approach will be > > * extract from the source files what information you can, and > * allow special comment tags to supplement and/or override this > > So you will get an inheritance tree which spans CPAN packages, for > instance. > > However, as always, don't wait for me. > I'm working on other stuff in P5EE now (the persistence system mainly). > > Stephen > > > >
