Yes, you're right, the documentation for the module is contained within the source code and is extracted during the build process. For a module this large, it probably made sense in the beginning to use this method to create the docs, but as the module has grown, I imagine it has become more difficult to manage. Perhaps moving the documentation into their own files is something for the developers to look at for the next release. Most of the changes I made to the docs involved replacing the TBD sections with the required information, as well as supplying more information about input parameters and return values for most of the functions.
> Date: Sun, 12 Jul 2009 18:23:30 -0700 > From: email@example.com > To: firstname.lastname@example.org > CC: email@example.com; firstname.lastname@example.org > Subject: Re: [perl-win32-gui-users] Win32::GUI Documentation > > On approximately 7/12/2009 5:41 PM, came the following characters from > the keyboard of Kevin Marshall: > > Reini, > > > > I understand where you are coming from, a diff would make replacement > > of the original files easier. I was, however, considering a complete > > rewrite of the documentation, including the structure, which would > > make patching the existing files interesting. An alternative would be > > to copy my docs over the docs generated in the build process, before > > doing "make install". Another way would be to edit the makefile to > > prevent the docs being generated, then move my docs into their place, > > then do "make install". For those people who use the PPMs they > > have less options. The best they can do is copy my docs over the > > originals after installing the PPM. It was suggested I set up a > > dedicated website for the documentation. This would certainly overcome > > any of these problems. > > Well, a dedicated website for the documentation only works-around these > problems. I think presently the source for the documentation is in the > source code files for the modules. If that is preserved, it is more > likely that the documentation will get updated when the code gets updated. > > Even if you do a complete rewrite of the documentation, if it is not > integrated with the module source in some way, it will likely not get > maintained over time. > > That said, I agree that the documentation could use some help; last I > looked at it, there were lots of TBD areas. > >