POD from code?

dgaramond2 has asked for the wisdom of the Perl Monks concerning the following question:

I have Perl module with code along the line of:

our %stuff = (
    foo => 'This is for alpha blah blah ...',
    bar => 'This is for beta blah blah ...',
    baz => 'This is for gamma blah blah ...',
    ...
);
[download]

I want document this to users. Is there an easy way to produce something like this from the code, instead of typing (and syncing) them manually:

=head3 %stuff

=over 4

=item * foo => 'This is for alpha blah blah ...'

=item * bar => 'This is for beta blah blah ...'

=item * baz => 'This is for gamma blah blah ...'

=back
[download]

I suspect this is the domain of PodWeaver and stuff, anyone care to give a guide on how to use this and possibly incorporate this into Dist::Zilla building process? Thanks.

Comment on POD from code? Select or Download Code

Replies are listed 'Best First'.
Re: POD from code? by Corion (Patriarch) on Nov 03, 2010 at 07:38 UTC
If I really want to do something like this, I do it the other way around, and create my data (not code) from POD: `my %stuff = map { /^=item * (\w+) => (.)/ ? $1 => $2 : die "Malformed + line: $_" } grep /^=item /, split /\r?\n/, <<'=cut'; =over 4 =item * foo => ... =item * bar => ... =item * baz => ... =back =cut` [download] Usually I find that approach to be a bit too much magic, but at least for the definition of configuration file entries, I found it helpfull as it forces me to write the documentation for every possible option together with its introduction into the program.	[reply] [d/l]
Re^2: POD from code? by JavaFan (Canon) on Nov 03, 2010 at 10:32 UTC
`split /\r?\n/` [download] Since 5.10.0, you can write that as: `split /\R/` [download]	[reply] [d/l] [select]
Re^2: POD from code? by LanX (Saint) on Nov 03, 2010 at 11:58 UTC
As a side note: An alternative to parsing here-docs is putting the POD after __DATA__. This clean separation between data and code could also facilitate automatic generation of this "Pod-Data"-hybrid. Or even isolating it into a dedicated module, since 'Text after __DATA__ may be read via the filehandle "PACKNAME::DATA"' Cheers Rolf	[reply]
Re^2: POD from code? by dgaramond2 (Monk) on Nov 03, 2010 at 22:15 UTC
Yup, that's a tiny bit on the syntax abuse side for me too. I don't mind doing this "manual sync" for test code (and in this case I believe this manual sync is necessary due to its very purpose). But for documentation, I'd like it to be automatic if possible. Because otherwise I'll have to test whether my documentation is up to date/complete.	[reply]
Re: POD from code? by Your Mother (Archbishop) on Nov 03, 2010 at 18:53 UTC
What Corion said. (Also, thanks for `\R`, JavaFan, I had missed that.) It's a bit much magic. If you're bent on it and are up for a learning experience, you could definitely do something for this with PPI.	[reply] [d/l]