Beefy Boxes and Bandwidth Generously Provided by pair Networks Cowboy Neal with Hat
Perl Monk, Perl Meditation
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??
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

In reply to On providing documentation with your modules by Jouke

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others chanting in the Monastery: (8)
    As of 2014-04-19 11:34 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      April first is:







      Results (480 votes), past polls