in reply to examples in CPAN distributions

There are a few distributions that create a cookbook CGI::Session::CookBook. This is basically an empty module with lots of package documentation. I am sure that there are other distributions that call it something else.

So I would say yes it is a relatively common practice to include examples