develooper Front page | perl.perl5.porters | Postings from February 2012

Documentation as attributes

Thread Next
Timo Grodzinski
February 24, 2012 08:06
Documentation as attributes
Message ID:
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") {

  - 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)

  - 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, ...)?


Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About