Documentation as attributes

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!

• Documentation as attributes by Timo Grodzinski
• Re: Documentation as attributes by Aristotle Pagaltzis
• Re: Documentation as attributes by Johan Vromans
• Re: Documentation as attributes by Nick Perez
• Re: Documentation as attributes by Alexander Hartmaier
• Re: Documentation as attributes by Ricardo Signes