I'm using a kind of simple template system to create my module.pod from a file module.tmpl.pod , extracting chunks from module.pm and including other source.

Just slurping the template, parsing module.pm and regexing the placeholders.

I'm using a test from my suite to generate the pod, so whenever I run the full suite my pod is up to date.

no rocket science...

I love having documentation close to the source, my POD doubles as comments at the head of each subroutine definition. If I were to go the route of an external module.pod- and I would if releasing anything to CPAN- I'd still write the POD source inside of module.pm and generate the pure-POD-file from that.

And in fact that looks like an intended use of POD::Tested, its processor can generate POD or test files from the same marked-up module. (I contacted the author with a comment earlier, can vouch the author is indeed dogfooding.)

My co-workers- the only other people who may look at this code- would not think to look at a separate POD file, but are grateful for good documentation in the module. So I am not going down the road of generating an external POD, even though I now see smooth ways of doing that with all desired features.

And a good-enough work-around would be to simply create the file as part of the test:

Given a file F<test.data> as below...

  File::Slurp::write_file("test.data",qq<<'END');
  Here is data
  that this function wants
  END

Results in

  # test continues here
[download]

hmm, some clarifications:

Pod structure:

How it works

• perldoc Module will display pod for Module.pod if found.
• only perldoc Module.pm will show pod for Module.pm
• in my system Module.pod is meant for the general API seen e.g. CPAN! (YMMV)
• Module.pm still contains valid pod! It's showing more detailed developer documentation
So if your collaborators open Module.pm they'll find what they need to see, plus maybe a disclaimer/link pointing to Module.pod

Workflow:

You seem to have the idea to automatically modify your Module.pm with test results.

I'm not a friend of such self modifying magic (at least outside my IDE and w/o human monitoring).

I prefer a strict separation between

• Model: e.g. Module.pm, test scripts
• View: Module.tpl.pod
• Controller: the "podcreator.pl" defining the logic
• Product: Module.pod, Readme(.pod),...

Known modules

I can't comment much on the CPAN modules you mentioned cause creating Pod from tests or vice versa wasn't on my task list yet.

I can imagine at least two cases where such a DRY workflow is beneficial:

a) sample code in POD (like in tutorials) which needs to be tested before publication

b) simple (unit) tests which are self documenting (e.g. showing use cases, function signature, and so on)

In any case I'd prefer to have a generic test script for such cases (the controller ) in my t/ directory which extracts the necessary data from the module's pod (the model ), to do the testing and create test reports and new POD (the product ).

Like this I can always resort to more complicated plain test scripts if embedding the logic within POD starts to over complicate things.

differences

I'm realizing now that your use case seems to be different or more fuzzy, so take my 2¢ as a meditation.

Thanks anyway this helped me improving my concept.

HTH =)

Cheers Rolf

PS: Je suis Charlie!

Is the author dogfooding? I don't see a lot of authors using these things

Hmmm, your last link shows that Moose uses inline tests; if it is a popularity contest, that is one heavy vote in favor!

Hmmm, your last link shows that Moose uses inline tests; if it is a popularity contest, that is one heavy vote in favor!

I doubt that :) Moose only has 10 authors. Its only used for the cookbook.

OTOH, Test::Inline isn't always listed as a dependency, http://grep.cpan.me/?q=%3Dbegin+testing reveals a few more distributions that depend on it ... kinda not really (at least a few authors tried it once upon a time)

Extracting tests from pod seems a bit backwards ... embedding makes a bit more sense, but still seems like busy work ... but installing the tests and telling the user to UTSL for complete/runnable examples? That seems "just right" :)

Consider Test::Class/https://metacpan.org/requires/distribution/Test-Class?sort=%5B%5B2%2C1%5D%5D which has 127 distributions depending on it ...

Like keanu once said, the problem is choice :)

Pod::PP has an include directive (and a require directive). The package includes a podpp script as a convenient command line wrapper around the module:

podpp Module.pm | perldoc | less for viewing or

podpp Module.pm | podtested for testing

Of course, you can use the podpp script as the basis of your own scripts to make viewing and testing easier.