[gexiv2] doc: Update ManagedStreamCallbacks documentation

[Jens Georg <jensgeorg src gnome org>]

commit c0d5ba754a90b7a8f401da295c352374afc425f4
Author: Jens Georg <mail jensge org>
Date:   Mon Mar 20 01:43:06 2017 +0100

    doc: Update ManagedStreamCallbacks documentation
    
    Signed-off-by: Jens Georg <mail jensge org>

 docs/reference/gexiv2-docs.xml     |    1 -
 docs/reference/gexiv2-sections.txt |   26 +++-----
 gexiv2/gexiv2-managed-stream.h     |  120 +++++++++++++++++++++++++++++++++++-
 3 files changed, 128 insertions(+), 19 deletions(-)
---
diff --git a/docs/reference/gexiv2-docs.xml b/docs/reference/gexiv2-docs.xml
index f9496fd..e3348f1 100644
--- a/docs/reference/gexiv2-docs.xml
+++ b/docs/reference/gexiv2-docs.xml
@@ -19,7 +19,6 @@
   <chapter>
       <title>GExiv2</title>
       <xi:include href="xml/gexiv2-log.xml"/>
-      <xi:include href="xml/gexiv2-managed-stream.xml"/>
       <xi:include href="xml/gexiv2-metadata.xml"/>
       <xi:include href="xml/gexiv2-preview-image.xml"/>
       <xi:include href="xml/gexiv2-preview-properties.xml"/>
diff --git a/docs/reference/gexiv2-sections.txt b/docs/reference/gexiv2-sections.txt
index 48d3ffa..b84f450 100644
--- a/docs/reference/gexiv2-sections.txt
+++ b/docs/reference/gexiv2-sections.txt
@@ -11,21 +11,6 @@ gexiv2_log_use_glib_logging
 </SECTION>
 
 <SECTION>
-<FILE>gexiv2-managed-stream</FILE>
-WrapperSeekOrigin
-Stream_CanSeek
-Stream_CanRead
-Stream_CanWrite
-Stream_Length
-Stream_Position
-Stream_Read
-Stream_Write
-Stream_Seek
-Stream_Flush
-ManagedStreamCallbacks
-</SECTION>
-
-<SECTION>
 <FILE>gexiv2-metadata</FILE>
 <TITLE>GExiv2Metadata</TITLE>
 GExiv2Orientation
@@ -105,6 +90,17 @@ gexiv2_metadata_set_gps_info
 gexiv2_metadata_delete_gps_info
 gexiv2_metadata_get_preview_properties
 gexiv2_metadata_get_preview_image
+WrapperSeekOrigin
+Stream_CanSeek
+Stream_CanRead
+Stream_CanWrite
+Stream_Length
+Stream_Position
+Stream_Read
+Stream_Write
+Stream_Seek
+Stream_Flush
+ManagedStreamCallbacks
 <SUBSECTION Standard>
 GEXIV2_IS_METADATA
 GEXIV2_IS_METADATA_CLASS
diff --git a/gexiv2/gexiv2-managed-stream.h b/gexiv2/gexiv2-managed-stream.h
index a745357..a7ef43c 100644
--- a/gexiv2/gexiv2-managed-stream.h
+++ b/gexiv2/gexiv2-managed-stream.h
@@ -3,27 +3,141 @@
  */
 
 
-#ifndef __GEXIV2_MANAGED_STREAM__
-#define __GEXIV2_MANAGED_STREAM__
+#ifndef GEXIV2_MANAGED_STREAM
+#define GEXIV2_MANAGED_STREAM
 
 #include <glib-object.h>
 
+/**
+ * WrapperSeekOrigin:
+ * @Begin: Seeking offset is relative to the beginning of the stream
+ * @Current: Seeking offset is relative to the current offset in the stream
+ * @End: Seeking offset is relative to the end of the stream
+ *
+ * Seek positions for #Stream_Seek
+ *
+ */
 typedef enum {
     Begin = 0,
     Current = 1,
     End = 2
 } WrapperSeekOrigin;
 
+/**
+ * Stream_CanSeek:
+ * @handle: Opaque storage for the native handle this function wil operate on
+ *
+ * Function that returns the seekability of the stream
+ *
+ * Returns: %TRUE if the stream object can be seeked
+ */
 typedef gboolean (*Stream_CanSeek)  (void *handle);
+
+/**
+ * Stream_CanRead:
+ * @handle: Opaque storage for the native handle this function wil operate on
+ *
+ * Function that returns the readability of the stream
+ *
+ * Returns: %TRUE if the stream object can be read from.
+ */
 typedef gboolean (*Stream_CanRead)  (void *handle);
+
+/**
+ * Stream_CanWrite:
+ * @handle: Opaque storage for the native handle this function wil operate on
+ *
+ * Function that returns the readability of the stream
+ *
+ * Returns: %TRUE if the stream object can be written to.
+ */
 typedef gboolean (*Stream_CanWrite) (void *handle);
+
+/**
+ * Stream_Length:
+ * @handle: Opaque storage for the native handle this function wil operate on
+ *
+ * Function to query the length of the stream
+ *
+ * Returns: The length of the stream
+ */
 typedef gint64   (*Stream_Length)   (void *handle);
+
+/**
+ * Stream_Position:
+ * @handle: Opaque storage for the native handle this function wil operate on
+ *
+ * Function to query the current position in the stream
+ *
+ * Returns: The current position
+ */
 typedef gint64   (*Stream_Position) (void *handle);
+
+/**
+ * Stream_Read:
+ * @handle: Opaque storage for the native handle this function wil operate on
+ * @buffer: Destination data to read into
+ * @offset: Offset in @buffer where data should be written to
+ * @count: Number of bytes to read
+ *
+ * Function to read data from the stream
+ *
+ * Returns: The number of bytes read, 0 on EOF or -1 on error.
+ */
 typedef gint32   (*Stream_Read)     (void *handle, void *buffer, gint32 offset, gint32 count);
+
+/**
+ * Stream_Write:
+ * @handle: Opaque storage for the native handle this function wil operate on
+ * @buffer: Source data to put into the stream
+ * @offset: Offset in @buffer where data should be read from
+ * @count: Number of bytes to write
+ *
+ * Function to write data to the stream
+ *
+ * Returns: The number of bytes written or -1 on error.
+ */
 typedef void     (*Stream_Write)    (void *handle, void *buffer, gint32 offset, gint32 count);
+
+/**
+ * Stream_Seek:
+ * @handle: Opaque storage for the native handle this function wil operate on
+ * @offset: Position in the stream, relative to @origin
+ * @origin: Determintes meaning of offset, being relative to current posision, start or end of the stream.
+ *
+ * Change the read or write position in the current stream
+ */
 typedef void     (*Stream_Seek)     (void *handle, gint64 offset, WrapperSeekOrigin origin);
+
+/**
+ * Stream_Flush:
+ * @handle: Opaque storage for the native handle this function wil operate on
+ *
+ * Schedule writing buffered data to the stream's real storage.
+ */
 typedef void     (*Stream_Flush)    (void *handle);
 
+/**
+ * ManagedStreamCallbacks:
+ * @handle: Storage for the native handle to be used with this stream
+ * @CanSeek: Pointer to a function that describes the seekability of @handle
+ * @CanRead: Pointer to a function that describes the readability of @handle
+ * @CanWrite: Pointer to a function that describes the writability of @handle
+ * @Length: Pointer to a function that gets the length of @handle
+ * @Position: Pointer to a function that gives the current location inside @handle
+ * @Read: Read bytes from the stream
+ * @Write: (nullable): Function pointer to write to the stream. Can be #NULL if @CanWrite returns #FALSE
+ * @Seek: Function pointer to seek in the stream.
+ * @Flush: (nullable): Function pointer schedule writing of all cached data to disk. Can
+ * be #NULL if @CanWrite returns #FALSE
+ *
+ * #ManagedStreamCallbacks is a set of callbacks that describe a stream that
+ * can be passed to gexiv2_metadata_open_stream() to read image meta-data from
+ * arbitrary data sources that can be mapped to this set of callbacks.
+ *
+ * At least @CanSeek and @CanRead need to return #TRUE and the relevant
+ * call-backs must not be #NULL to be any useful.
+ */
 struct _ManagedStreamCallbacks {
     void *handle;
     Stream_CanSeek CanSeek;
@@ -39,5 +153,5 @@ struct _ManagedStreamCallbacks {
 
 typedef struct _ManagedStreamCallbacks ManagedStreamCallbacks;
 
-#endif /* __GEXIV2_MANAGED_STREAM__ */
+#endif /* GEXIV2_MANAGED_STREAM */