Documentation tweaks

In particular, document how 'free' callbacks propagate exceptions.

diff --git a/lib/Variable/Magic.pm b/lib/Variable/Magic.pm
index b3b7316bb0a69d6912e40b6da684fcd9cc88e44d..5b2086b0f52aba7f52da8ea66bde447e78748ede 100644 (file)
--- a/lib/Variable/Magic.pm
+++ b/lib/Variable/Magic.pm
@@ -79,6 +79,12 @@ This also makes catching individual events easier than with C<tie>, where you ha
 
 =item *
 
+Magic is multivalued.
+
+You can safely apply different kinds of magics to the same variable, and each of them will be invoked successively.
+
+=item *
+
 Magic is type-agnostic.
 
 The same magic can be applied on scalars, arrays, hashes, subs or globs.
@@ -86,7 +92,7 @@ But the same hook (see below for a list) may trigger differently depending on th
 
 =item *
 
-Magic is invisible at the Perl level.
+Magic is invisible at Perl level.
 
 Magical and non-magical variables cannot be distinguished with C<ref>, C<tied> or another trick.
 
@@ -136,7 +142,8 @@ Please note that this is different from undefining the variable, even though the
 
 I<free>
 
-This magic is called when an object is destroyed as the result of the variable going out of scope (but not when the variable is undefined).
+This magic is called when a variable is destroyed as the result of going out of scope (but not when it is undefined).
+It behaves roughly like Perl object destructors (i.e. C<DESTROY> methods), except that exceptions thrown from inside a I<free> callback will always be propagated to the surrounding code.
 
 =item *