Give your modules a good SYNOPSIS
If the abstract for your module is up to snuff, then have a look at the SYNOPSIS to see whether you could improve that in a CPAN Day release. The SYNOPSIS should briefly show typical usage of the headline features of your module.
Here are some guidelines for a good SYNOPSIS:
- Keep it brief. You don't need to show everything about your module.
- Make sure the code presented actually works.
- If there are logically different sections to the SYNOPSIS, break it into multiple code blocks, with a lead-in comment for each.
A bit more on each of those in turn.
Keep it brief
The SYNOPSIS shouldn't try and demonstrate every last feature. Instead, aim for the smallest example that illustrates the core essence of your module.
Have a look at the SYNOPSIS for Moose: Moose has a lot of features, but the SYNOPSIS just shows a simple class and a subclass.
Personally, I don't think you should include use strict; and use warnings; in your SYNOPSIS, unless it's relevant to your module (as with strictures). It should be a distilled example, with no distractions. Opinion's split on this point though, so decide for yourself.
Minimise any comments you include, lining them up off to the right, if you can. You can give longer examples in body of the documentation.
Make sure the code works
It's frustrating if someone copies the SYNOPSIS and it doesn't work. Sometimes it's down to a simple syntax error, but sometimes it's because the interface has changed but the SYNOPSIS wasn't updated.
You could add a test to make sure that your SYNOPSIS works, using Test::Synopsis. If you use Dist::Zilla, you could look at Dist::Zilla::Plugin::Test::Synopsis.
I like the idea of a DZ plugin that extracts the SYNOPSIS from one or more test files.
Split different concepts into different sections
If there are distinctly separate concepts to your module, then split the SYNOPSIS into multiple sections. A good example where this makes sense is exporter modules: have one code block that shows the exporting module, and another that shows the importing code. A good example of this is Sub::Exporter.
Perl hacker since 1992.
Thanks for the reference to Test::Synopsis. Is there an easy way to get it to load feature say? It's unhappy with lots of my examples: "Do you need to predeclare say?"
One thing I ended up adding to my test suite for one package was an "examples.t" file, which contains tests for all the examples in the synopsis and throughout the documentation (including the small examples per method and the EXAMPLES section). This compares the expected output, which Test::Synopsis doesn't have. I wanted to make sure I caught any regressions in anything I used in the documentation because that would be particularly embarrassing. The downside is keeping things in sync.
Add this to your pod, just before the SYNOPSIS code:
Toby, thank you very much!