[PATCH] Clarify documentation for FT_Stream_IoFunc

[Stephen Holdaway]

>From f54c01c6dc599f3c1f17f34a6cb9bd5180407c1d Mon Sep 17 00:00:00 2001
From: Stephen Holdaway <stecman@gmail.com>
Date: Sun, 3 Jul 2022 20:26:31 +1200
Subject: [PATCH] Clarify documentation for FT_Stream_IoFunc

The existing doc comment on `FT_Stream_IoFunc` hinted at the dual
seek/read behavior required for custom stream implementations to work,
but it didn't explicitly explain it. Without looking at the internals
of FreeType, it was easy for someone to assume their implementation
should handle both seek and read operations all the time. If this is
done, you get a variety of errors, but mostly just Unknown_File_Format (0x2).

I fell into this trap myself, and while it seems dumb, searching online
found a few unresolved threads from other poor souls who were having
this exact issue in the past.
---
 include/freetype/ftsystem.h | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/include/freetype/ftsystem.h b/include/freetype/ftsystem.h
index 5f8aec7b7..e26c7169e 100644
--- a/include/freetype/ftsystem.h
+++ b/include/freetype/ftsystem.h
@@ -229,7 +229,8 @@ FT_BEGIN_HEADER
    *     A handle to the source stream.
    *
    *   offset ::
-   *     The offset of read in stream (always from start).
+   *     The offset from the start of the stream to seek to if this is a seek
+   *     operation (see note).
    *
    *   buffer ::
    *     The address of the read buffer.
@@ -241,8 +242,12 @@ FT_BEGIN_HEADER
    *   The number of bytes effectively read by the stream.
    *
    * @note:
-   *   This function might be called to perform a seek or skip operation with
-   *   a `count` of~0.  A non-zero return value then indicates an error.
+   *   This function performs a seek OR a read operation depending on the
+   *   argument values. When `count` is zero, the operation is a seek to
+   *   `offset` bytes. When `count` is > 0, the operation is a read of `count`
+   *   bytes from the current position in the stream, and the `offset` value
+   *   should be ignored. For seek operations, a non-zero return value
+   *   indicates an error.
    *
    */
   typedef unsigned long
-- 
2.37.0