From 5f8ed1049f90b1a95a39a127fabd43b2147789d0 Mon Sep 17 00:00:00 2001
From: John Cupitt <jcupitt@gmail.com>
Date: Wed, 2 Oct 2024 13:30:46 +0100
Subject: [PATCH] improve TargetCustom docs

---
 src/SourceCustom.php |  9 ++++++---
 src/TargetCustom.php | 35 ++++++++++++++++++++++++++---------
 2 files changed, 32 insertions(+), 12 deletions(-)

diff --git a/src/SourceCustom.php b/src/SourceCustom.php
index 47d9bb4..20ecc7c 100644
--- a/src/SourceCustom.php
+++ b/src/SourceCustom.php
@@ -20,6 +20,7 @@ public function __construct()
 
     /**
      * Attach a read handler.
+     *
      * The interface is similar to fread. The handler is given a number
      * of bytes to fetch, and should return a bytes-like object containing up
      * to that number of bytes. If there is no more data available, it should
@@ -32,16 +33,18 @@ public function onRead(callable $callback): void
 
     /**
      * Attach a seek handler.
+     *
      * The interface is the same as fseek, so the handler is passed
      * parameters for $offset and $whence with the same meanings.
      * However, the handler MUST return the new seek position. A simple way
      * to do this is to call ftell() and return that result.
      * Seek handlers are optional. If you do not set one, your source will be
      * treated as unseekable and libvips will do extra caching.
+     *
      * $whence in particular:
-     *  0 => start
-     *  1 => current position
-     *  2 => end
+     *  - 0 => start
+     *  - 1 => current position
+     *  - 2 => end
      */
     public function onSeek(callable $callback): void
     {
diff --git a/src/TargetCustom.php b/src/TargetCustom.php
index dedb149..99b1757 100644
--- a/src/TargetCustom.php
+++ b/src/TargetCustom.php
@@ -20,8 +20,13 @@ public function __construct()
 
     /**
      * Attach a write handler.
-     * The interface is exactly as fwrite. The handler is given a bytes-like object to write,
-     * and should return the number of bytes written.
+     *
+     * The interface is similar to fwrite(). The handler is given a 
+     * bytes-like object to write, and should return the number of bytes 
+     * written. 
+     *
+     * Unlike fwrite, you should return -1 on error.
+     *
      * @throws Exception
      */
     public function onWrite(callable $callback): void
@@ -31,10 +36,12 @@ public function onWrite(callable $callback): void
 
     /**
      * Attach a read handler.
-     * The interface is similar to fread. The handler is given a number
+     *
+     * The interface is similar to fread(). The handler is given a number
      * of bytes to fetch, and should return a bytes-like object containing up
      * to that number of bytes. If there is no more data available, it should
      * return null.
+     *
      * Read handlers on VipsTarget are optional. If you do not set one, your
      * target will be treated as unreadable and libvips will be unable to
      * write some file types (just TIFF, as of the time of writing).
@@ -48,16 +55,19 @@ public function onRead(callable $callback): void
 
     /**
      * Attach a seek handler.
-     * The interface is the same as fseek, so the handler is passed
+     *
+     * The interface is similar to fseek, so the handler is passed
      * parameters for $offset and $whence with the same meanings.
      * However, the handler MUST return the new seek position. A simple way
      * to do this is to call ftell() and return that result.
+     *
      * Seek handlers are optional. If you do not set one, your source will be
      * treated as unseekable and libvips will do extra caching.
+     *
      * $whence in particular:
-     *  0 => start
-     *  1 => current position
-     *  2 => end
+     *  - 0 => start
+     *  - 1 => current position
+     *  - 2 => end
      */
     public function onSeek(callable $callback): void
     {
@@ -68,9 +78,12 @@ public function onSeek(callable $callback): void
 
     /**
      * Attach an end handler.
+     *
      * This optional handler is called at the end of write. It should do any
      * cleaning up necessary, and return 0 on success and -1 on error.
-     * Automatically falls back to onFinish if libvips <8.13
+     *
+     * Automatically falls back to onFinish if libvips <8.13.
+     *
      * @throws Exception
      */
     public function onEnd(callable $callback): void
@@ -84,8 +97,12 @@ public function onEnd(callable $callback): void
 
     /**
      * Attach a finish handler.
-     * For libvips 8.13 and later, this method is deprecated in favour of @throws Exception
+     *
+     * For libvips 8.13 and later, this method is deprecated in favour of 
+     * onEnd().
+     *
      * @see TargetCustom::onEnd()
+     * @throws Exception
      */
     public function onFinish(callable $callback): void
     {