Re: RFC: Automated Testing Of Code Examples In Documentation and "=for example"

[Michael G Schwern]

On Thu, Jul 27, 2000 at 06:53:23PM -0400, Chaim Frenkel wrote:
> How do you know that sample code in the documentation is correct?
> That it compiled? Or that it generated the correct result?
> 
> The documentor will need to state the expected result, so that
> both the reader and testing scripts can validate.

Well, we can test this in tiers, depending on how much work the POD
author wants to do.

First tier:  Does it compile?
Second:      Does it compile without warnings?  Pass B::Lint?  etc...
Third:       The POD author could somehow indicate what the correct
             result is and we run the exampl against that result.

Something like that.

Running the first tier will probablly nail a large swath of stupid
mistakes.  After that it will probably drop off rapidly while the
amount of POD author annoyance increases rapidly.  tchrist makes a
good point, we can't make it anyting but easy to write POD.

-- 

Michael G Schwern      http://www.pobox.com/~schwern/      [EMAIL PROTECTED]
Just Another Stupid Consultant                      Perl6 Kwalitee Ashuranse
Sometimes these hairstyles are exaggerated beyond the laws of physics
          - Unknown narrator speaking about Anime