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!

We're "on the same page," or close to it. I'm creating supplementary tests from in-source-POD, and pure-POD from that same in-source-POD. The main difference between your workflow idea and my current practice is that I haven't separated the POD template out into its own file, à chacun son goût...
1. My sample code is in POD inside of Module.pm
2. POD::Tested provides a controller script pod_tested.pl that can generate both (or either of) Module.pod and Module.t as products of Module.pm's POD
3. There's no magic re-writing of the original Module.pm.
I now have some tests asserting that my examples are correct, and pure-POD files alongside the modules. There's a little more to it than that "in real life" but that's the basics.