|Welcome to the Monastery|
It's not a maintenance nightmare at all. You simply document how to check a return value. The scripter doesn't have to know anything about it. They just use the interface. They get a result, and test that result for true or false (or however the rest of the system does things). The mechanics are homologous to testing a result code through a method like a lot of modules already have in their interface. If the coders aren't checking return values, the program still breaks at the same point.
brian, brian, brian. *sighs* If only 90% of people who type Perl code into an editor1 actually followed a tenth of what you say. But, alas, that is not the case. In fact, it is so often not the case that ... let's just say they already have enough rope to hang themselves with.
You simply document how to check a return value. The scripter doesn't have to know anything about it. They just use the interface. They get a result, and test that result for true or false (or however the rest of the system does things).
In 7 jobs located in 5 states over the last 4 years where I've used Perl, documentation was done in exactly two places. In one, a multi-billion dollar consortium that handles 40% of all credit card transactions, the documentation was done so we could have something to review code from. It was never actually kept up to date, nor was it any form of developer doc. In the other, a 100-million dollar insurance firm, since I wrote the system from scratch, I documented exactly enough for my protegee to keep the system running.
What happened in the other 5 jobs? Bupkus! That's what happened. Motorola, BankOne, a tiny startup ... none of these firms documented their Perl code, processes, APIs ... nothing! You cannot assume anyone will document code, let alone Perl code. Remember - Perl isn't a programming language, so it's got to be really easy to figure out.
If the coders aren't checking return values, the program still breaks at the same point.
Actually, it won't. See, 90% of all Perl code currently running on some production system somewhere doesn't
As a consultant, that's the code that I have to support. And, because the people who wrote this pus-dripping, camel-vomiting dreck either have CS or MIS degrees, they obviously know everything there is to know about Perl. So, when someone comes up and says "Here, let's go ahead and make Perl feel more like VB", they're going to go "Ooooh!" and jump all over it.
Except, they'll screw it up. But, since these flea-bitten, dog-kissing, motherless goats wouldn't recognize a development process if it painted itself pink and purple and danced naked on a bar wearing a fruit basket on its head, they DIP2 like it's 1959. Once it's in production, getting it out is like giving medicine to a toddler. Even though the child is only 30 inches talls and 25 pounds, it still takes 2 adults to hold the squirmy bastard long enough to squirt 4ml of pink goop into its mouth3.
While this is partly tongue-in-cheek (could you tell?) ... I'm also being deadly serious. This proposal requires a lot of API documentation. I can definitely see a CPAN module using it, especially one like Mail::Sendmail for the example you gave above. Advocating development shops use it when the language doesn't have explicit support built in can be ... well ... disheartening for those of us who will have to maintain said code. I mean, can't you see how this is hurting the children?!? Think of the children, brian! The children!!!
Being right, does not endow the right to be rude; politeness costs nothing.