[freetype2] master d5d048bbf: doc: Clarify description of `FT_Stream_IoFunc`.

[Werner Lemberg]

branch: master
commit d5d048bbfe1bcfae18fa5948284c95f89d8f33a0
Author: Stephen Holdaway <stecman@gmail.com>
Commit: Werner Lemberg <wl@gnu.org>

    doc: Clarify description of `FT_Stream_IoFunc`.
    
    The existing documentation comments 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` (error code
    0x02).
---
 include/freetype/ftsystem.h | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/include/freetype/ftsystem.h b/include/freetype/ftsystem.h
index 5f8aec7b7..acbf7041c 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,13 @@ 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.  If `count` is zero, the operation is a seek to
+   *   `offset` bytes.  If `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