byterock

So it is Moose day here in the Dist-Pen

So I am finally back to Moose after many many days with Dist::Zilla and Pod::Weaver as to today I am going to see how I can use the Moose::MOP, Dist:Zill and Pod::Weaver all together.

What I am look at today is the [Consumes] section plug-in which is suppose to run out read the meta-classes of my Moose objects and then print out all the Roles that a class consumes. I am not sure what results I will get but is should be fun to see.

So all I need to do is add this in my 'weaver.ini'

[Generic / OVERVIEW]

++[Consumes]

[Collect / ATTRIBUTES]

and after I install it with cpan and do the old clean and build with dzil I get

=head1 CONSUMES

=over 4

=item * L<Database::Accessor::Types>

=back

in my Accessor.pm which is perfectly correct as in that file I have

 use Moose;

    with qw(Database::Accessor::Types);

Snooping about a bit in the other '.pms' I see no 'Consumes' sections as none of the other '.pm' files in my distribution consume a role so that is good.

Unfortunately there is no 'header' attribute for this plug-in so you are stuck with the default header.

That one went so smoothly I and going to add in another similar [ClassMopper] this time it will root though the meta-class and gather up all the At Tributes and methods and write them up for me. Sounds very useful for me. So like the last plug-in all I need to do is add in

[Consumes]

++[ClassMopper]

[Collect / ATTRIBUTES]

to my 'weaver.ini' file, insall the plug-in and the the tried and true dzil clean and build to get;

=back

=head1 ATTRIBUTES

=head2 available_drivers

Reader: available_drivers

Writer: available_drivers

Type: ArrayRef

This documentation was automatically generated.

=head2 conditions

…

Now I am not going to boar you with the four hundred plus lines of other pod that was generated as you can get the picture of what was created from the above.
This plug-in comes with a few neat features one is that it will use the 'documentation' option in the output. So if I add in the following

    has available_drivers =>(

        isa => 'ArrayRef',

        is  => 'rw'

++    documentation=>"Returns an ArrayRef of HasRefs the DADs that are installed. The keys in the HashRef are 'DAD=>DAD name,class=>the DB class,ver=>the DAD Version'"

    );

in my Accessor.pm I will get this when I do the next build;

=head1 ATTRIBUTES

=head2 available_drivers

Reader: available_drivers

Writer: available_drivers

Type: ArrayRef

Additional documentation: Returns an ArrayRef of HasRefs the DADs that are installed. The keys in the HashRef are 'DAD=>DAD name,class=>the DB class,ver=>the DAD Version'

This documentation was automatically generated.

Sweet though not 100% of what I want a quick way to generate some POD. Some of the other features is that is will skip and private attributes, those that start with '_' and it will skip a number of the background Moose-Poop and Perl functions and attributes like @ISA, does, BUILDARGS etc.

The plug-in does have a number of attributes that let you configure your output.
Setting the 'include_private' attribute to a true value will add in any attributes that start with an '_'.

You can also suppress the output of the the Attributes or Methods sections at will by stetting either 'skip_attributes' or 'skip_methods' attributes to true. I suppose you could set them both to true but then you wouldn't get any output.

If you do not like that 'This documentation was automatically generated.' sentence you can suppress that by setting the 'no_tagline' attribute to true.

Finally there is the 'skip_method_list' where you can add in more than the standard methods to skip over.

So all in all a very handy bit of code for use Moose-heads. Myself I would most likely use this plug-in to generate the first run of my POD and then take it out of my 'weaver.ini' file. The fix up the generate POD as, if you remember, I do not want to have my attributes listed alphabetically but rather grouped together by functionality.

It would be nice if this plug-in was a little more developed and one could change some to the headings or other content but it is a good start.