Front page | perl.perl5.porters |
Postings from February 2012
On Fri, 24 Feb 2012 09:53:06 +0100
Timo Grodzinski <timo.grodzinski@googlemail.com> wrote:
> With documentation in POD, it is impossible (without standards) to
> establish a relationship between documentation and symbols like subs
> and variables.
> But this relationship is a huge benefit of documentation systems like
> Javadoc or Doxygen.
>
> The idea is to provide documentation as metadata to symbols.
>
> Common Lisp has a similar concept:
>
> (defun foo ()
> "does something useful"
> (...))
>
> (documentation 'foo 'function) => "does something usefuel"
>
> In Perl:
>
> sub foo :doc("does something very useful") {
> ...;
> }
>
> pros:
> - standardized way to document
> - documentation is processible
> - IDEs are able to lookup doc for specific subs/vars
> - POD is ugly, mandatory blank lines, ... (it's a matter of taste)
>
> cons:
> - expensive to parse (perl has to compile source)
> - Perl is due to its dynamic nature not compareable to Java/C++,
> - what about object-attributes (has in Moose, Mouse, Moo, ...)?
>
> Discuss!
>
Frankly, this is better solved outside of core. If you look at Moose
and its use of the documentation argument to the attribute builder
[has()], and MooseX::Getopt and its use of said documentation, you will
see a somewhat successful example of documentation paired with code.
POD has its warts, but there are some decent tools[1] for managing it.
[1] https://metacpan.org/module/Pod::Weaver
--
Nicholas Perez
XMPP/Email: nick@nickandperla.net
https://metacpan.org/author/NPEREZ
http://github.com/nperez
Thread Previous
|
Thread Next