On Tue, 18 Dec 2012 09:37:36 -0700 Maurice Mengel <mauricemen...@gmail.com> wrote:
> 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! So there is one particular solution that makes organizing your documentation trivial and that is Pod::Weaver. There is a Dist::Zilla plugin that makes working with Pod::Weaver rather painless and automatic. This lets you write POD associated with each method and attribute and have it rolled up for you when you build the distribution. If you want to take a look at what I end up using for most of modules, see: http://nickandperla.net/gitweb/?p=weaver.ini.git;a=tree That said, this won't address your inherited methods bit. The Moose documentation itself doesn't even do that. But that isn't to say you couldn't do that yourself by hand. Rocco also has an attempt at "inherited" documentation, but I am not too sure how far along it is. Maybe you can poke him about it: https://github.com/rcaputo/pod-plexus -- Nicholas Perez XMPP/Email: n...@nickandperla.net https://metacpan.org/author/NPEREZ http://github.com/nperez
