On providing documentation with your modules

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?

Jouke Visser
Speaking at the 2004 O'Reilly Open Source Convention about pVoice

Comment on On providing documentation with your modules

Replies are listed 'Best First'.
•Re: On providing documentation with your modules by merlyn (Sage) on Apr 17, 2004 at 13:16 UTC
It sounds like your module is similar to Curses, which is a thin wrapper around `curses(3)`. But even though it's only a thin wrapper, my experience of using the Perl view of the library is mostly frustrating with the scarcity of docs. I was similarly annoyed at the initial documentation for Tk, which again, was just a thin wrapper around the `Tk` library. It's gotten a lot better over time, because the documentation has been made more "native", although often only by text-wrangling the `Tk` lib docs in a consistent way. Oh yeah, and I'm still annoyed at Mac::Glue, which requires me to understand all of AppleScript, most of OSA, and then some weirdnesses that are "obvious" for the Perl-OSA layer. So please. anything you can give in the way of examples of each invocation, careful descriptions of the differences and limitations, and known gotchas, would all be most appreciated. Understand that people want concepts, structure, and examples. While the original docs for the original lib may provide concepts and some structure, they do not provide Perl-native structure or examples, and that's what you should fill in. -- Randal L. Schwartz, Perl hacker Be sure to read my standard disclaimer if this is a reply.	[reply]
Re: On providing documentation with your modules by leira (Monk) on Apr 17, 2004 at 05:27 UTC
I think you definitely shouldn't copy and paste, because duplicating documentation, like duplicating code, can lead to a maintenance nightmare. You'd need to keep abreast of changes, and keep things updated, and I'm sure you don't want to do that. I'd suggest that you make it clear in your own POD that extensive documentation is available elsewhere, and where it can be found. Provide links to this other documentation, so that those viewing the documentation in a format where these links are useful (like on the CPAN web site) can easily get to the other documentation without rummaging. Linda	[reply]
Re: On providing documentation with your modules by matija (Priest) on Apr 17, 2004 at 05:54 UTC
I suppose if all you're doing is just providing the glue between Perl and the library, you _could_ get away with that. However, if there are any cases where what the Perl code is doing differs from what the C++ code is doing, you should document the hell out of them. It would also be good to provide several example programs, that people can study and use as their starting point. I generaly dislike cargo cult programming, but when you're familiarizing yourself with a new library, sometimes using a modern amount of CC is the only way to get your feet wet. Compare what you are doing to PerlTk - although most of the calls look very much like the calls in TclTk, there are enough subtle differences that they felt the need to write a lot of very good documentation for each class.	[reply]
Re: On providing documentation with your modules by Abigail-II (Bishop) on Apr 17, 2004 at 09:57 UTC
I would refer in the POD to where the documentation can be found. However, it seems to annoy lots of people (specially those on non-Unix systems) if the Perl core distribution refers to the system documentation. I guess it's hard to satisfy everyone. Abigail	[reply]
Re: On providing documentation with your modules by chromatic (Archbishop) on Apr 17, 2004 at 17:32 UTC
Perhaps you could write a tutorial that explains and writes out example code, as does SDL::Tutorial.	[reply]
Re: On providing documentation with your modules by diotalevi (Canon) on Apr 17, 2004 at 15:39 UTC
BerkeleyDB is the same way except that it is often unclear how much of the underlying C API is supported. You've got to be clear in every case where your API differs from the C API you are wrapping.	[reply]
Re: On providing documentation with your modules by flyingmoose (Priest) on Apr 18, 2004 at 00:32 UTC
I've seen a lot of XS modules that skimped on docs because they thought they could, when in reality, the syntax can and might be different. Try googling for info on OpenGL.pm and you won't find much, and the POD doesn't help either... so where, oh where, is that canonical spinning Gouraud shaded cube in Perl? I certaintly can't find it. So, even to this day, I haven't used OpenGL.pm Bottom line, documentation is great stuff, and if you can take an extra 30 minutes and include a simple example with that XS module, I'll thank you for it! :) Even if you're own module is not XS-only, and you just have an API, a few lines of code using that API is always useful as well. Another bad habit I've seen is CPAN pages that say "for documentation visit http://xxx.yyy.zz, which is a problem because then your handy perldoc in an xterm is suddenly no good.	[reply]
Re: On providing documentation with your modules by gmpassos (Priest) on Apr 17, 2004 at 16:54 UTC
If you can make an automatic insertion of the BASS docs into the POD of your module you could duplicate the data. But if this can't be automatic you should just point to an URL. In your POD you could add only some simple example, or informations about what is the module and some differences between your interface and the BASS interface, since they are in different languages. You says that wxPerl don't need POD, well, it needs, not about the classes that it wrappes, but about the way that it wrappes. Graciliano M. P. "Creativity is the expression of the liberty".	[reply]
Re: On providing documentation with your modules by Vautrin (Hermit) on Apr 18, 2004 at 15:51 UTC
Your wrapper most likely contains perl based functions, right? Does each and every one of these perl functions do the same thing as their BLAST equivalents? If they don't, I would write a short blurb about the functions. You don't need to be extremely verbose, just saying "`foo($bar)` is the same as the bass equivalent of `foo(int bar)`, and the return value will always be a hash instead of the bass `char[2][256]`" So, if everything is exactly the same I see no problems with referring people to other documentation. But if it isn't, be sure to document the changes, so people don't have to screw with them to figure out how they work. CGI.pm is a good example of how you don't always have to document all of your features for the documentation to be successful. For instance, CGI.pm uses function which are named after their corresponding HTML tags. So, the POD has a section where it explains that if it's available in HTML, it's a function spelled with lowercase letters. IMHO, this makes the documentation much more concise because it doesn't have a list of functions which all do the same thing, and is a great way to go. Want to support the EFF and FSF by buying cool stuff? Click here.	[reply] [d/l] [select]

Back to Meditations