[vlc-commits] memstream: document

[Rémi Denis-Courmont]

vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Wed Jan 15 18:43:22 2020 +0200| [723f7122abd39f9d94a36ff59ec4d8dfd6b7007c] | committer: Rémi Denis-Courmont

memstream: document

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=723f7122abd39f9d94a36ff59ec4d8dfd6b7007c
---

 include/vlc_memstream.h | 96 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 94 insertions(+), 2 deletions(-)

diff --git a/include/vlc_memstream.h b/include/vlc_memstream.h
index 0ed78a7315..328982d8ce 100644
--- a/include/vlc_memstream.h
+++ b/include/vlc_memstream.h
@@ -24,6 +24,19 @@
 # include <stdarg.h>
 # include <stdio.h>
 
+/**
+ * \defgroup memstream In-memory byte streams
+ * \ingroup cext
+ *
+ * In-memory byte stream are a portable wrapper for in-memory formatted output
+ * byte streams. Compare with POSIX @c open_memstream().
+ *
+ * @{
+ */
+
+/**
+ * In-memory stream object.
+ */
 struct vlc_memstream
 {
     union
@@ -31,33 +44,109 @@ struct vlc_memstream
         FILE *stream;
         int error;
     };
-    char *ptr;
-    size_t length;
+    char *ptr; /**< Buffer start address */ 
+    size_t length; /**< Buffer length in bytes */
 };
 
+/**
+ * Initializes a byte stream object.
+ *
+ * @note Even when this function fails, the stream object is initialized and
+ * can be used safely. It is sufficient to check for errors from
+ * vlc_memstream_flush() and vlc_memstream_close().
+ *
+ * Compare with POSIX @c open_memstream().
+ *
+ * @param ms byte stream object
+ *
+ * @retval 0 on success
+ * @retval EOF on error
+ */
 VLC_API
 int vlc_memstream_open(struct vlc_memstream *ms);
 
+/**
+ * Flushes a byte stream object.
+ *
+ * This function ensures that any previous write to the byte stream is flushed
+ * and the in-memory buffer is synchronized. It can be used observe the content
+ * of the buffer before the final vlc_memstream_close().
+ *
+ * Compare with @c fflush().
+ *
+ * @note vlc_memstream_close() implicitly flushes the object.
+ * Calling vlc_memstream_flush() before closing is thus superfluous.
+ *
+ * @warning @c ms->ptr must <b>not</b> be freed. It can only be freed after
+ * a successful call to vlc_memstream_close().
+ *
+ * @retval 0 success, i.e., @c ms->ptr and @c ms->length are valid
+ * @retval EOF failure (@c ms->ptr and @c ms->length are unspecified)
+ */
 VLC_API
 int vlc_memstream_flush(struct vlc_memstream *ms) VLC_USED;
 
+/**
+ * Closes a byte stream object.
+ *
+ * This function flushes the stream object, releases any underlying
+ * resource, except for the heap-allocated formatted buffer @c ms->ptr,
+ * and deinitializes the object.
+ *
+ * On success, the caller is responsible for freeing the buffer with @c free().
+ *
+ * Compare with @c fclose().
+ *
+ * \retval 0 success
+ * \retval EOF failure (@c ms->ptr and @c ms->length are unspecified)
+ */
 VLC_API
 int vlc_memstream_close(struct vlc_memstream *ms) VLC_USED;
 
+/**
+ * Appends a binary blob to a byte stream.
+ *
+ * Compare with @c fwrite().
+ *
+ * @param ptr start address of the blob
+ * @param length byte length of the blob
+ */
 VLC_API
 size_t vlc_memstream_write(struct vlc_memstream *ms,
                            const void *ptr, size_t len);
 
+/**
+ * Appends a single byte to a byte stream.
+ *
+ * Compare with @c putc() or @c fputc().
+ *
+ * @param Unsigned byte value converted to int.
+ */
 VLC_API
 int vlc_memstream_putc(struct vlc_memstream *ms, int c);
 
+/**
+ * Appends a nul-terminated string to a byte stream.
+ *
+ * Compare with @c fputs().
+ */
 VLC_API
 int vlc_memstream_puts(struct vlc_memstream *ms, const char *str);
 
+/**
+ * Appends a formatted string to a byte stream.
+ *
+ * Compare with @c vfprintf().
+ */
 VLC_API
 int vlc_memstream_vprintf(struct vlc_memstream *ms, const char *fmt,
                           va_list args);
 
+/**
+ * Appends a formatted string to a byte stream.
+ *
+ * Compare with @c fprintf().
+ */
 VLC_API
 int vlc_memstream_printf(struct vlc_memstream *s, const char *fmt,
                          ...) VLC_FORMAT(2,3);
@@ -73,4 +162,7 @@ static inline int vlc_memstream_puts_len(struct vlc_memstream *ms,
         vlc_memstream_puts_len(ms,s,__builtin_strlen(s)) : \
         vlc_memstream_puts(ms,s))
 # endif
+
+/** @} */
+
 #endif /* VLC_MEMSTREAM_H */