POE::Component::Server::TCP bug fixes, possibly incompatible

Greetings,

During the course of writing a tutorial I've been noticing discrepancies
between POE::Component::Server::TCP's documentation and code.  I have
filed some initial tickets:

    http://rt.cpan.org/Ticket/Display.html?id=47855
    http://rt.cpan.org/Ticket/Display.html?id=47854
    http://rt.cpan.org/Ticket/Display.html?id=47853
    http://rt.cpan.org/Ticket/Display.html?id=47852

Most are pretty straightforward.  However, 47855 requires a bit of
discussion.

The problem is that the ClientConnected callback does not actually
receive a socket in ARG0.  ARG0 has been spliced off in the
POE::Wheel::ReadWrite constructor, so ARG0 is actually the ClientArgs
parameter.  This change was implemented nearly 4 years ago (to fix a
leaking socket problem), so anything that actually uses ARG0 will break
if the code is changed to match the documentation.

How should the code be changed?  Should it be made conservatively, so
that any code relying on ARG0 being ClientArgs continues to work?
Should it be fixed to match the documentation?

One advantage of out and out breaking old code  is that ClientArgs could
actually be flattened into ARG1..$#_.  Right now it's a little awkward
and confusing that ClientArgs is required to be an arrayref, yet nothing
in POE::Component::Server::TCP is actually using it as one.

--
Michael Fowler
www.shoebox.net