document how errors are handled and reported

diff --git a/Screenshot.pm b/Screenshot.pm
index abb226e8703d8aefaf926319b8eb79e9895f6818..6f99518d4bb82d4579b4c4841db75fc2e91cbf6f 100644 (file)
--- a/Screenshot.pm
+++ b/Screenshot.pm
@@ -255,6 +255,11 @@ So setting all 4 values to 0 retrieves the whole window.
   # 10x10 pixel at the bottom right corner
   my $bott_right_10 = screenshot(left => -10, top => -10, ...);
 
+If screenshot() fails, it will return nothing, and the cause of the
+failure can be retrieved via Imager->errstr, so typical use could be:
+
+  my $img = screenshot(...) or die Imager->errstr;
+
 =item have_win32
 
 Returns true if Win32 support is available.