The module looks like (and probably is) an offshoot of Schwern's Carp::Assert. If not, they should have similiar functionality. The difference is that assertions.pm can be toggled via a command line switch, unlike Carp::Assert. There can also, now be different types of assertions; it's no longer an all or nothing type of thing. This gets rid of the need for a DEBUG variable, like Carp::Assert's. It's also probably optimized away a little better, although I didn't spend the time to look into the internals of either module.

I agree that the documentation is sparse. Although a lot of specific modules are created for those people who understand the basic concept behind them already (MIDI, for instance, expects you to know something about MIDI files but even then has great documentation), a core module should be expected to either explain itself in documentation or be tutorialed. Otherwise, a lot of programmers may be stuck trying to figure out the exact functionality of assertions.

The problem with the current documentation is the brevity of the last line: "The assertion pragma associates to its lexical scope one or several assertion tags. Then, to activate the execution of the assertions subroutines in this scope, these tags must be given to perl via the -A command-line option." One had to use the assertions pragma to allow assertion subroutines in certain scopes, and _then_ if somebody toggled -A, then all assertions would be activated. If somebody toggled -A, they could also choose what flags they want to assert as a parameter.

Furthermore, the author needs to document how assertion.pm works with scopes. If use assertions is used in a lower scope, does it over-ride the upper scope? That's what it looks like to me. Is '_' the variable that holds the upper scope's assertions variables? Does use assertion qw/x y/ mean that x and y both must be toggled, or either can be toggled to work (it looks like both...)? Is there an 'or' for assertions? So something can be asserted with foo or bar? Does a later  use assertion in the same scope over-ride an earlier one?

Hopefully, the author will rewrite the documentation as Perl 5.9.0 comes out. Because assertion.pm has a version number of 0.01, it's very likely, in fact.