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