Thanks to you all. You've given me a lot to think about.

After pondering, it does seem to me that there's no reason not to just put it in the documentation, with a sample dump and all if I must. POD or whatever, within the object doesn't seem as clever now as it did at first! lol.

Thanks!

I would strongly recommend a solution where docstrings and pod are easily mirrored, but I'm searching myself.

As a suggestion, some people do things (roughly) like this:

$class::doc=<<"__doc__";
=pod
docstring bla bvla

bla
=cut
__doc__
[download]

Yes, this works. I've used the technique to write documented lists:

my @items = map { /^=item (.*)/ ? $1 : () } split /\n/, <<'=cut';

=begin

=over 4

=item Hello

The first item must always be C<Hello>

=item World

The second item must always be C<World>

=back

=cut

print "Items: @items\n";
[download]

Ungh. That sounds ugly. Embrace POD as the one true way to document your code. If you want a module to return its documention (which, at face value, sounds strange) then convert your module name to a path name and run pod2* on that file. Basically class Foo::Bar's get translated to system 'pod2html', 'Foo/Bar.pm' or something of that sort.

I believe you could capture pod2text's output and return that as a string if you really want the class to return something.

- doug

If I understand right, you want those comments to be available when you dump or stringify the object, right? In that case you do not need to keep the documentation in all those instances, but you should rather overload the "freezer" so that whenever you attemtp to dump the object it adds the comments to whereever it thinks is best. See $Data::Dumper::Freezer in Data::Dumper.

What sort of comments are you thinking of adding?