From c18dd26e967f90c4e8ec7d6e921005b44ec91948 Mon Sep 17 00:00:00 2001
From: Tony Cook <tony@develop-help.com>
Date: Sat, 12 Nov 2011 13:37:04 +1100
Subject: [PATCH] [rt #72369] Document the return value of the filter() method

---
 Changes                |  3 +++
 lib/Imager/Filters.pod | 19 +++++++++++++++++++
 t/x20spell.t           |  1 +
 3 files changed, 23 insertions(+)

diff --git a/Changes b/Changes
index 86dda4bc..8ff45732 100644
--- 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 b614b1e6..6e14c8a8 100644
--- 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 d519c87e..4b97643b 100644
--- a/t/x20spell.t
+++ b/t/x20spell.t
@@ -42,6 +42,7 @@ eg
 gaussian
 ie
 infix
+invocant
 metadata
 paletted
 postfix
-- 
2.39.5