From: Vincent Pit <vince@profvince.com>
Date: Sun, 4 Oct 2009 15:10:59 +0000 (+0200)
Subject: Deprecate all the user signature stuff for december 2009
X-Git-Tag: v0.38~2
X-Git-Url: http://git.vpit.fr/?a=commitdiff_plain;h=745e2c898af9671e06e60785082caa6c291387d2;p=perl%2Fmodules%2FVariable-Magic.git

Deprecate all the user signature stuff for december 2009
---

diff --git a/lib/Variable/Magic.pm b/lib/Variable/Magic.pm
index fe96a19..7928af0 100644
--- a/lib/Variable/Magic.pm
+++ b/lib/Variable/Magic.pm
@@ -208,8 +208,7 @@ BEGIN {
 
 =head2 C<wizard>
 
-    wizard sig      => ...,
-           data     => sub { ... },
+    wizard data     => sub { ... },
            get      => sub { my ($ref, $data [, $op]) = @_; ... },
            set      => sub { my ($ref, $data [, $op]) = @_; ... },
            len      => sub { my ($ref, $data, $len [, $op]) = @_; ... ; return $newlen; },
@@ -237,6 +236,8 @@ The numerical signature.
 If not specified or undefined, a random signature is generated.
 If the signature matches an already defined magic, then the existant magic object is returned.
 
+This option is B<deprecated> and will be removed in december 2009.
+
 =item *
 
 C<data>
@@ -324,6 +325,8 @@ That's the way L</wizard> creates them when no signature is supplied.
     # Generate a signature
     my $sig = gensig;
 
+This function is B<deprecated> and will be removed in december 2009.
+
 =head2 C<getsig>
 
     getsig $wiz
@@ -333,13 +336,14 @@ This accessor returns the magic signature of this wizard.
     # Get $wiz signature
     my $sig = getsig $wiz;
 
+This function is B<deprecated> and will be removed in december 2009.
+
 =head2 C<cast>
 
-    cast [$@%&*]var, [$wiz|$sig], ...
+    cast [$@%&*]var, $wiz, ...
 
 This function associates C<$wiz> magic to the variable supplied, without overwriting any other kind of magic.
-You can also supply the numeric signature C<$sig> instead of C<$wiz>.
-It returns true on success or when C<$wiz> magic is already present, and croaks on error or when no magic corresponds to the given signature (in case a C<$sig> was supplied).
+It returns true on success or when C<$wiz> magic is already present, and croaks on error.
 All extra arguments specified after C<$wiz> are passed to the private data constructor in C<@_[1 .. @_-1]>.
 If the variable isn't a hash, any C<uvar> callback of the wizard is safely ignored.
 
@@ -400,21 +404,20 @@ Of course, this example does nothing with the values that are added after the C<
 
 =head2 C<getdata>
 
-    getdata [$@%&*]var, [$wiz|$sig]
+    getdata [$@%&*]var, $wiz
 
-This accessor fetches the private data associated with the magic C<$wiz> (or the signature C<$sig>) in the variable.
-It croaks when C<$wiz> or C<$sig> do not represent a valid magic object, and returns an empty list if no such magic is attached to the variable or when the wizard has no data constructor.
+This accessor fetches the private data associated with the magic C<$wiz> in the variable.
+It croaks when C<$wiz> do not represent a valid magic object, and returns an empty list if no such magic is attached to the variable or when the wizard has no data constructor.
 
     # Get the attached data, or undef if the wizard does not attach any.
     my $data = getdata $x, $wiz;
 
 =head2 C<dispell>
 
-    dispell [$@%&*]variable, [$wiz|$sig]
+    dispell [$@%&*]variable, $wiz
 
 The exact opposite of L</cast> : it dissociates C<$wiz> magic from the variable.
-You can also pass the magic signature C<$sig> as the second argument.
-This function returns true on success, C<0> when no magic represented by C<$wiz> or C<$sig> could be found in the variable, and croaks if the supplied wizard or signature is invalid.
+This function returns true on success, C<0> when no magic represented by C<$wiz> could be found in the variable, and croaks if the supplied wizard is invalid.
 
     # Dispell now.
     die 'no such magic in $x' unless dispell $x, $wiz;
@@ -425,14 +428,20 @@ This function returns true on success, C<0> when no magic represented by C<$wiz>
 
 The minimum integer used as a signature for user-defined magic.
 
+This constant is B<deprecated> and will be removed in december 2009.
+
 =head2 C<SIG_MAX>
 
 The maximum integer used as a signature for user-defined magic.
 
+This constant is B<deprecated> and will be removed in december 2009.
+
 =head2 C<SIG_NBR>
 
     SIG_NBR = SIG_MAX - SIG_MIN + 1
 
+This constant is B<deprecated> and will be removed in december 2009.
+
 =head2 C<MGf_COPY>
 
 Evaluates to true iff the 'copy' magic is available.