moose and pod

[Maurice Mengel]

Hi!

I am new to the list and also still new to Moose. I wonder how exactly to
document my Moose classes. I am sure you discussed this before, but I
couldn't find much on the list archive. Perhaps it's time to add something
on this matter to the documentation. Perhaps in Best Practices. Or
elsewhere in Manual. Perhaps I am also missing something. Please point me
in the right direction if I do.

I guess there are some things that seem fairly clear and other things where
we might have different opinions. It seems some people like inherited stuff
(including roles) to be listed in each class that inherits stuff and others
like it only in the class which defines stuff. That shouldn't stop us. We
could make suggestions for both solutions. This is perl after all.

The first two sections seem pretty much standard. How should I refer to
inherited attributes and methods?

=head1 Attributes

=head1 Methods

=head1 Inherited Stuff [;-)]

Thanks!

[Jeff Benton]

I add another level under the attributes and methods to differentiate public and private.
I also add another section in there for Roles.

In my Roles, I make sure if there are required methods, that I document what the expected api is supposed to be.

=head2 REQUIRES

=cut

requires qw(method1);

=head3 method1(%args)

Returns ...

Arg 0: self
Arg 1: args hash ...

=cut

[Buddy Burden]

Maurice,

> It seems some people like inherited stuff
> (including roles) to be listed in each class that inherits stuff and others
> like it only in the class which defines stuff.

It seems to me that the problem with listing methods (and/or
attributes) that you inherit is that, if the base class changes, the
POD for all subclasses then has to change as well. This sets you up
for having your POD and your code be out of sync, and it's pretty
difficult to maintain, particularly if the same author is not
responsible for both.

I suppose this is midly off-topic from your original question, but I'd
be curious to know how the fans of documenting inherited methods
answer this objection.


-- Buddy


PS-- Don't get me wrong: if you *don't* document the inherited
methods, it can make it hideously difficult for your users to find the
POD for a given method. I have this problem all the time with
Class::MOP and Moose itself. So much so that I wrote the code below.
So it's a bit of a lose-lose proposition, really.

# find a method in a class hierarchy
sub whose_method
{
my ($classname, $methodname) = @_;
my $meta = $classname->meta;

my @results;
CLASS: foreach ($meta->can('linearized_isa') ? (reverse
$meta->linearized_isa) : ($classname))
{
my $meta = $_->meta;

# check roles of the class before the class itself
if ($meta->can('calculate_all_roles'))
{
foreach ($meta->calculate_all_roles)
{
my %m = map { $_ => 1 } $_->get_method_list;
push @results, $_->name and next CLASS if $m{$methodname};
}
}

my %m = map { $_ => 1 } $meta->get_method_list;
push @results, $_ if $m{$methodname};
}

return @results;
}

I don't expect that's perfect, but it's seemed to work pretty well for
me so far.

[Maurice Mengel]

Thanks for quick replies! Lot's of good stuff.

Personally, I am not a fan of documenting anything twice, so I don't like
to document inherited stuff in the inheriting class, but I have seen
modules that seem to create documentation automatically. That might work
(in many cases), especially if you are the author of the other class.

I'd prefer to link to the parent/role class. I suspect that could also be
automatized with podweaver. But before I even think about that I think
someone should propose a standard (or two) for how classes should be
described in pod. As far as I can tell/remember, such a standard is not
covered by any of the perl books, the new perlootut (
http://perldoc.perl.org/perlootut.html) or the Moose manual.

Thanks for the code and the weaver.ini. I will study those. Both look
great. I should be able to come up with a solution that works for me based
on this. Thanks again!

On Tue, Dec 18, 2012 at 12:08 PM, Nick Perez <ni...@nickandperla.net> wrote:

> o has an attempt at "inherited" documentation, but I am not
> too sure h
>

[Mike Friedman]

If you want to automate some documentation features with regards to
inheritance and role composition, you can use these two modules:

https://metacpan.org/module/Pod::Weaver::Section::Extends
https://metacpan.org/module/Pod::Weaver::Section::Consumes


Mike