[rt #72369] Document the return value of the filter() method

diff --git a/Changes b/Changes
index 86dda4bc1e1e4e99d230c41cbdf42b55ad4052e5..8ff45732d7bac55ce593e82f76bbcb4cdd14eff4 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,8 @@
 Imager release history.  Older releases can be found in Changes.old
 
+ - document the return value of the filter() method.
+   https://rt.cpan.org/Ticket/Display.html?id=72369
+
  - properly increment the Imager::Matrix2d $VERSION.
 
  - actually include the Imager::Test tests in the dist

diff --git a/lib/Imager/Filters.pod b/lib/Imager/Filters.pod
index b614b1e6a21707e6b0c7894695005dbb5599def9..6e14c8a813805e4c9e0988621258635460bb28a1 100644 (file)
--- a/lib/Imager/Filters.pod
+++ b/lib/Imager/Filters.pod
@@ -46,6 +46,13 @@ many other possible parameters, see L</Types of Filters> below.
 
 =back
 
+Returns the invocant (C<$self>) on success, returns a false value on
+failure.  You can call C<< $self->errstr >> to determine the cause of
+the failure.
+
+  $self->filter(type => $type, ...)
+    or die $self->errstr;
+
 =back
 
 =head2 Types of Filters
@@ -608,6 +615,18 @@ level image object from $self and $self itself respectively.
 
 The function you supply must modify the image in place.
 
+To indicate an error, die with an error message followed by a
+newline. C<filter()> will store the error message as the C<errstr()>
+for the invocant and return false to indicate failure.
+
+  sub my_filter {
+    my %opts = @_;
+    _is_valid($opts{myparam})
+      or die "myparam invalid!\n";
+
+    # actually do the filtering...
+  }
+
 =back
 
 See L<Imager::Filter::Mandelbrot> for an example.

diff --git a/t/x20spell.t b/t/x20spell.t
index d519c87e3529d7b1fd6fcf2a9d9fe1eedddfdb56..4b97643b4bc5fdf24d37eb43c7659b8d57a0e6c5 100644 (file)
--- a/t/x20spell.t
+++ b/t/x20spell.t
@@ -42,6 +42,7 @@ eg
 gaussian
 ie
 infix
+invocant
 metadata
 paletted
 postfix