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

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.

* Alexander Hartmaier <alex.hartmaier [at] gmail> [2012-02-28T15:29:44] > Perl 6 has a solution for this already, maybe it should trickle down to > Perl 5?!

The Perl 6 solution is built on a number of significant differences between Perl 5 and Perl 6, which are, I think, not easy (if possible) to reconcile.

There are a number of third-party tools for doing "autodoc" style documentation of Perl with Pod. I think it is reasonable for them to continue to exist and fight it out until there is a clear victor *and* a reason to integrate it into the core language distribution.

Which means this proposal is dead on arrival because parsing Perl means running Perl and you can safely bet that MetaCPAN and search.cpan.org aren’t going to run code just to show its docs. It’s still possible to extract the docs with PPI or its approach, but why choose a design that makes that necessary as a starting point? Something more in keeping with the spirit of POD would avoid the hassle altogether.