I don't expect programmers to automatically know they can call $object->new and if they try it without reading the docs then I would be in the "serves 'em right" camp. Does that do the same thing as calling new() on a classname (like all other class methods do?) or does it make a clone of the object? If it clones it, is it a deep or shallow copy? Do the two instances really share the same filehandle? There are just two many questions to be answered for something like that to not be documented.

The patch for removing references to this from the perldocs was accepted with almost no disagreement. I was very surprised by that. Given how contentious the debate is, I was certain that more people on P5P would speak out against the patch.