Front page | perl.p5ee |
Postings from November 2001
> > I would assume Inline POD is the way to go. > > I am wondering if anyone has experiences counter to this. > > This is going to be an area of contention... > > I think POD has to go for this project. At least in its default form. > > We need something way more structured, that maintains API details to the > extreme, like JavaDOC does, only we want something easier/better than > JavaDOC. Ah, a discussion I can contribute to, finally! ;-) I've given this a lot of thought, having been disappointed in my own projects with the maintainability of POD, and have gone to the trouble of creating a preliminary system for maintaining API documentation using a combination of XML and perl comments. If you want to see an example of what I've got, here it is: The project is called ModInfo and is on SourceForge: http://www.sf.net/projects/modinfo (it's young, still) An example of the system's use can be found in my GUI builder project Guido on SourceForge. One of the files in the application's CVS directory might be a good example: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/guido/guido/lib/Guido/Applicat ion.pm?rev=1.9&content-type=text/vnd.viewcvs-markup (Whereever you see # MODINFO comments is where the documentation is being placed) You can also see the preliminary usage documentation here: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/modinfo/ModInfo/ModInfo/Tutori al.pod?rev=1.1.1.1&content-type=text/vnd.viewcvs-markup I designed the system to do two things, a) make it easy to update your API documentation when you make changes to your code, and b) get the API info into XML stored alongside the module itself so that you can convert it to whatever you want whenever you want. Along the way, I ended up designing the primary module for the system so that it could parse the XML into a set of perl objects, which enables runtime inspection of API documentation from your script (intellisense, anyone? ;-) For those interested in such things, I somewhat copied the BeanInfo API from the JavaBeans spec for the object structure. I deviated when I had to. I also went so far as to work in something I call pseudo-typing. With pseudo-typing, you specify in your API documentation whether you expect a parameter or property to be an integer or string, for example, even though Perl doesn't really care what you pass in or get out. This is solely to help the developer understand your code, not to enforce any real datatyping. I find that it's helping me understand my own Guido project much better, and I've squashed several bugs just because I'm using the documentation now. Oh, and there are two forms of the API documentation (so far), one is embedded POD: http://guido.sourceforge.net/doc/lib/Guido/Application.html And one is a simple JavaDoc style API document: http://guido.sourceforge.net/doc/interface/Guido/Application.html The embedded POD is automatically updatable using the "INTERFACE" header as a delimiter within the code. A script inserts the pod in the right place. I'd love to hear ideas on how this could be improved or extended. One more thing, an example of one of the .mfo (xml) files that is stored by the system is attached for you to see. jptThread Previous | Thread Next