Ah, yes, much better, IMHO. I'd do things slightly differently:

package Example::Person;

use overload '""' => \&stringify;

sub new
{
    my( $name, $age )= @_;
    return bless { name=>$name, age=>$age };
}

sub stringify
{
    my( $self )= @_;
    return "$self->{name} ($self->{age} years)";
}
[download]

Which can be used like:

require Example::Person;
my $me= Example::Person->new( "Tye", 12 );
print "Hi, I'm $me.\n";
# prints:
# Hi, I'm Tye (12 years).
[download]

I don't find "use strict" nor "use warnings" more than distracting and I didn't like how both your and Ovid's examples conflated the code for a module (that uses overloading) with the code that makes use of that module. Yes, I think that has the potential to confuse people. It also makes the example less useful as a starting point if someone wants code to cut'n'paste.

This example is small enough that the key concepts are easy to spot in it and the distractions are minimal. Of course, it only covers a very small part of overload.pm so other examples are needed. I don't think all of these examples need to be complete and fully self-contained. In fact, I'd find it rather obnoxious if only complete and fully self-contained examples were used.

There are some simple modules where "synopsis" can also serve as "real example" but for many modules a "real example" necessarily makes for a lousy synopsis. It is unfortunate that the boilerplate POD has led to near ubiquitous inclusion of a synopsis but very rare inclusion of real, full examples. I don't think trying to repurpose "synopsis" as "real, full example" is a smart strategy for improving that situation.

Adding more useful and complete, full examples can be beneficial. In the case of overload.pm, such work nearly leads to creation of a full module, and a full module is what is required anyway if someone wants a starting point to just copy. That was the purpose (so I've been told) of Math::BigInt. Perhaps since then it has accumulated too many patches for it to still be ideally suited for that original purpose. So I'm not surprised nor do I find it a deficiency in the documentation that someone wanting to use overload.pm turned to the source code of something like Math::BigInt.

I don't really understand overload, and have never had reason to use it. But your example gets my vote as the clearest in the thread. I don't care about the advanced use, I just want to understand the *basics*. I can usually figure out advanced stuff myself once I've got the basics down.

I think in this case as well, splitting the code into two 'files' makes it a lot easier to understand.