Re: examples in CPAN distributions

[rinceWind]

For trivial modules, the examples are encompassed by the tests, in t/*.t which is the standard place. For test data, there is no convention.

For something non-trivial, having example code is a good idea. Again there is no convention that I'm aware of.

Do you have a preference? If so, please tell us. Expressing it in Perlmonks is a good way to get feedback, and to set conventions and standards in the Perl community.

[grinder]

The tests of a module provide good clues as to how to use the module, but one has to realise that some of those tests may be there to see how the modules deals with incorrect usages. There may be lots of obscure corner case tests designed to achieve a high level of code coverage.

Sometimes it can be hard to spot what is essential.

Real examples are better in that there's none of the test infrastructure, or the test suite's goals, getting in the way. You can take one and then start to bend it into shape to solve your own task. This is my usual approach to HTML::Parser, since I don't use it enough to remember all of the API. Having a usable skeleton is a great way to start hanging lumps of flesh off it :)

Also, as far as conventions and standards regarding modules goes, if it isn't discussed on the module-authors mailing list, it will become neither. This is not to dismiss Perlmonks, but these things tend to get thrashed out over there. People sometimes don't realise that a lot of the Perl community doesn't hang out on Perlmonks.

[shigetsu]

People sometimes don't realise that a lot of the Perl community doesn't hang out on Perlmonks.

May I take the freedom and point to somewhere else?

http://lists.perl.org is a pretty good start too.

Please don't reply as it was merely intended as a pointer; we would be getting more and more offtopic if we'd do otherwise.

[zby]

I don't feel qualified to ask this question on module-authors mailing list - at least for the one reason that I have not read that list bofore. If anyone would ask this question on this list please post the link to the thread in the archives here if that is possible.