Mailing List Archive: Perl: porters

Documentation as attributes

Index | Next | Previous | View Threaded

timo.grodzinski at googlemail

Feb 24, 2012, 12:53 AM

Post #1 of 6 (145 views)
Permalink

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!

nick at nickandperla

Feb 24, 2012, 8:15 AM

Post #2 of 6 (135 views)
Permalink

Re: Documentation as attributes [In reply to]

On Fri, 24 Feb 2012 09:53:06 +0100
Timo Grodzinski <timo.grodzinski [at] googlemail> 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 [at] nickandperla
https://metacpan.org/author/NPEREZ
http://github.com/nperez

alex.hartmaier at gmail

Feb 28, 2012, 12:29 PM

Post #3 of 6 (123 views)
Permalink

Re: Documentation as attributes [In reply to]

Perl 6 has a solution for this already, maybe it should trickle down to
Perl 5?!

-Alex (abraxxa)

On Fri, Feb 24, 2012 at 5:15 PM, Nick Perez <nick [at] nickandperla> wrote:

> On Fri, 24 Feb 2012 09:53:06 +0100
> Timo Grodzinski <timo.grodzinski [at] googlemail> 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 [at] nickandperla
> https://metacpan.org/author/NPEREZ
> http://github.com/nperez
>

perl.p5p at rjbs

Feb 28, 2012, 3:55 PM

Post #4 of 6 (119 views)
Permalink

Re: Documentation as attributes [In reply to]

* 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.

I don't see that happening in the foreseeable future.

--
rjbs

Attachments:

signature.asc (0.48 KB)

jvromans at squirrel

Feb 29, 2012, 12:34 AM

Post #5 of 6 (123 views)
Permalink

Re: Documentation as attributes [In reply to]

Timo Grodzinski <timo.grodzinski [at] googlemail> writes:

> With documentation in POD, it is impossible (without standards) to
> establish a relationship between documentation and symbols like subs
> and variables.

Right.

> sub foo :doc("does something very useful") {

This is 'a standard' as referred to in the opening paragraph.

Alternative standards are thinkable, and possible. Given the current use
of POD, some additional conventions in POD to make this information
extractable seem a more logical way to go.

-- Johan

pagaltzis at gmx

Feb 29, 2012, 4:24 AM

Post #6 of 6 (119 views)
Permalink

Re: Documentation as attributes [In reply to]

* Timo Grodzinski <timo.grodzinski [at] googlemail> [2012-02-24 17:10]:
> cons:
> - expensive to parse (perl has to compile source)

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.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads