[OPEN-ILS-DEV] Code Documentation Proposal

[Dan Scott]

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.