When you release a module on CPAN, you provide POD documentation. That has to be one of the first rules of the "CPAN authors club". However: what if your module is just an XS wrapper around an existing C(++) library that is already extensively documented itself?
For example, wxPerl is a wrapper around wxWidgets, which itself is extensively documented. When I started with wxPerl I found it very annoying that I had to use the wxWidgets documentation, because there was no POD documentation on the Perl module itself. However after some time, I began to understand that there was no need to add POD documentation, because if you were able to read the documenation on one class, you could understand the whole set of documentation. It would just have been overkill
Now I'm in the same position Mattia Barbon was in when he started creating wxPerl. I'm creating a wrapper around BASS, which will probably appear on CPAN as Audio::BASSXS soon. BASS comes with documentation in Microsoft Help format (CHM), and since it's a Windows DLL (not available on other platforms than Windows), it seems there's no need to provide more documentation.
What do you think? Would it suffice to refer to the CHM documentation that is already in the BASS distribution, or should I copy-and-paste the documentation into POD?
For example, wxPerl is a wrapper around wxWidgets, which itself is extensively documented. When I started with wxPerl I found it very annoying that I had to use the wxWidgets documentation, because there was no POD documentation on the Perl module itself. However after some time, I began to understand that there was no need to add POD documentation, because if you were able to read the documenation on one class, you could understand the whole set of documentation. It would just have been overkill
Now I'm in the same position Mattia Barbon was in when he started creating wxPerl. I'm creating a wrapper around BASS, which will probably appear on CPAN as Audio::BASSXS soon. BASS comes with documentation in Microsoft Help format (CHM), and since it's a Windows DLL (not available on other platforms than Windows), it seems there's no need to provide more documentation.
What do you think? Would it suffice to refer to the CHM documentation that is already in the BASS distribution, or should I copy-and-paste the documentation into POD?
Back to
Meditations