jdv has asked for the wisdom of the Perl Monks concerning the following question:

I've written simple Perl bindings to a C++ library using XS++ and Module::Build::WithXSpp. The XS++ code is a single file that defines six classes - nothing fancy, just 80 lines of class and method definitions that directly mirror the C++ API.

My question regards how best to document the distribution using POD. The upper namespace is 'Compress::DSRC'. I currently have a single, auto-generated 'Compress/DSRC.pm' that loads the XS and contains skeleton POD, and clearly I can add documentation here (I've seen POD in XS). However, the classes that users will actually use are e.g. 'Compress::DSRC::Reader' or 'Compress::DSRC::Writer'. Should I create '*.pm' files for each class that contain nothing but POD (other than package declaration, etc?) or is there an acceptable way to document each class within the single 'Compress/DSRC.pm' file?

Replies are listed 'Best First'.
Re: Organizing POD for an XS++ module
by Anonymous Monk on Oct 15, 2015 at 19:14 UTC
    It is acceptable to have Foo::Bar::Baz documentation in Foo::Bar, esp if Foo::Bar wouldn't have much documentation of its own
[reply]

      Do you happen to have a brief example of how to organize the POD in this case, or a pointer to an existing module that does it this way? Everything I've done in the past has had separate files and POD for each class. Can you just start a new section with another "=head1 NAME"?

[reply]

        this is the pattern, i can't think of an example ATM, but this is the pattern, seen it a million times, with non-ambiguous optional args documentation 

        =head1 NAME

Foo::Bar  - the best foo you can bar 

=head2 Foo::Bar::Baz

The baz of the bar in the foo

=head3 Foo::Bar::Baz->new

=head3 $baz->qux

=head3 $baz->qux( $slice )

=head3 $baz->qux( $slice, $thickness )

Its delicious, takes no args, one arg, or two args

=head2 Foo::Bar::Norf

=head3 Foo::Bar::Norf->new

=head3 $norf->qux

=head3 $norf->qux( $barf )

=head3 $norf->qux( $barf, $taffy )

Norf norf norf norf norf barf!

=cut

        [download]

        update: http://grep.cpan.me/?q=%3Dhead2.*%3F-%3Enew&page=5

        https://metacpan.org/search?q=%3A%3Areader+%3A%3Awriter&size=20&search_type=modules -> XML::Tape

        update: from memory, XML::Twig, but its HUGE and a tutorial 

        Simplifying XML processing
NAME
... ... ...
CLASSES
METHODS
    XML::Twig
    XML::Twig::Elt
    cond
    XML::Twig::XPath
    XML::Twig::XPath::Elt
    XML::Twig::Entity_list
...

        [download]

        I like all the methods showing up in TOC

[reply]
[d/l]
[select]

Back to Seekers of Perl Wisdom