Make the purpose of done_testing and the plan clearer

[schwern]

A few people were doing this:

use Test::More;  END { done_testing }

This defeats the protections of done_testing because...

1. done_testing() should only run if all your tests have executed.
2. END blocks always run, even if your code exits or dies.

I figure people should be able to work that out from those principles, but @dagolden pointed out that #1 isn't documented. The whole point of the plan is a bit muddled.

So....

1. Improve the docs for done_testing() to include more information to help a user know how to use it correctly.
2. Avoid simply listing things not to do, like END { done_testing }

I only caught three people doing END { done_testing }, not enough to take up space in the docs. I'd rather focus on conveying the principles so people can think intelligently about done_testing rather than list every mistake we've seen.

[Ovid]

I'm embarrassed to say that I used END { done_testing } before and yes, I should have known better. We all have "thinkos" and this one is important enough to document. Sure, you can explain done_testing all you want, but many (most?) people scan docs, they don't read them.

[dagolden]

Nit -- END blocks are not executed for exec() or when signal are caught. (c.f perlmod)

Since the harness will catch any non-zero exit code anyway (from die(), signals or "exit $nonzero") it seems the major benefit of done_testing is to help Test::More catch premature exit 0.

[exodist]

I wonder if I can make done_testing warn if it detects it is in an END block. Not completely sure how to accomplish that, but I am guessing there is a var somewhere that will let us detect a global cleanup?

Or this:

sub done_testing {
    ...
    my $e = eval { die };
    warn "..." if $e =~ m/global destruction/;
}

Not sure if I got that completely right, but I know an exception thrown in an END block has a similar message.

[exodist]

 $ perl -e 'END{ my $e = eval { die "XXX" }; print "XXX: $e\n" }'                                                                                        (master:*)[~/projects/Test-More]
XXX: 

nevermind

[exodist]

${^GLOBAL_PHASE} looks like it is what I want

Not available in all perl versions, but I can at least use it on ones that do.

[exodist]

I am just going to document the issue. Adding END detection is a problem because using caller to detect END is the only viable way, but that causes SEGV in some cases, which is bad.