On Tue, Sep 25, 2012 at 01:49:31PM -0700, Jeffrey Bond wrote: > Greetings Evergreen Devs, > > Catalyst is currently seeking to provide in line documentation for perl > modules on the Evergreen project. The goal of this effort is to provide new > developers and contributors a better glimpse into the code. It will also > clear up misunderstandings about code that may, or may not be deprecated > from use. Documentation for the code will include sub routine comments > formatted in ASCIIdocs format, and completing all OpenSRF API calls with > proper information.
Hmm. I'm curious about the choice of AsciiDoc format for the inline documentation; wouldn't POD markup make much more sense (so that "perldoc OpenILS::Actor::Friends" can return something)? Or is there a perldoc variant that understands AsciiDoc? > Details for the proposal can be found > here<http://evergreen-ils.org/dokuwiki/doku.php?id=dev:proposal:perl_module_documentation> > > We wrote up this proposal assuming the perl modules we've committed to > match the desires of the community. Please give us your input on what type > of documentation should be added or taken away. Also we would like your > input on what modules should be documented. We picked what we felt would be > the best choice, but would rather comment on what would help the community > the most. It's pretty tough for me to have an opinion about which modules are most valuable in terms of inline documentation, because when I need to I tend to dig into the code itself. I guess it depends on which modules areas the community is most interested in extending or making use of.