sdb: add documentation to buffer functions

librz/util/sdb/src/buffer.c

@@ -1,8 +1,25 @@
 // SPDX-FileCopyrightText: unknown
 // SPDX-License-Identifier: CC-PDDC
 
+/** \file
+ * \brief Operations on buffers.
+ *
+ * Provide simple buffered write functionality: functions to write to
+ * memory buffer until filled out and then write to file descriptor
+ * via provided callback, or to flush buffer.
+ */
+
 #include "buffer.h"
 
+/**
+ * \brief Initialize a buffer.
+ * \param[out] s The buffer to initialize.
+ * \param[in] op The writing operation of the buffer.
+ * \param fd The file descriptor to write to.
+ * \param buf The underlying buffer associated with \p s.
+ * \param len The size in bytes of the underlying buffer.
+ * \attention This function owns \p buf for as long as \p s is used.
+ */
 void buffer_init(buffer *s, BufferOp op, int fd, char *buf, ut32 len) {
 	s->x = buf;
 	s->fd = fd;
@@ -11,6 +28,14 @@ void buffer_init(buffer *s, BufferOp op, int fd, char *buf, ut32 len) {
 	s->n = len;
 }
 
+/** \internal
+ * \brief Unbuffered write of a message.
+ * \param op The writing operation.
+ * \param fd The file descriptor to write to.
+ * \param buf The message to write.
+ * \param len The size in bytes of the message to write.
+ * \return \c 1 for success, \c 0 for failure.
+ */
 static int allwrite(BufferOp op, int fd, const char *buf, ut32 len) {
 	ut32 w;
 	while (len > 0) {
@@ -24,6 +49,11 @@ static int allwrite(BufferOp op, int fd, const char *buf, ut32 len) {
 	return 1;
 }
 
+/**
+ * \brief Flush (write out) buffered data.
+ * \param s The buffer containing buffered data.
+ * \return \c 1 for success, \c 0 for failure.
+ */
 int buffer_flush(buffer *s) {
 	int p = s->p;
 	if (!p) {
@@ -33,6 +63,12 @@ int buffer_flush(buffer *s) {
 	return allwrite(s->op, s->fd, s->x, p);
 }
 
+/**
+ * \brief Buffered write of message.
+ * \param s The buffer to operate on.
+ * \param buf The message to write.
+ * \param len The length of the message in bytes.
+ */
 int buffer_putalign(buffer *s, const char *buf, ut32 len) {
 	ut32 n;
 	if (!s || !s->x || !buf) {
@@ -53,6 +89,16 @@ int buffer_putalign(buffer *s, const char *buf, ut32 len) {
 	return 1;
 }
 
+/**
+ * \brief Flush buffer and then flush message.
+ * \param s The buffer to operate on.
+ * \param buf The message to write.
+ * \param len The length of the message in bytes.
+ * \return \c 1 for success, \c 0 for failure.
+ *
+ * Whatever buffered data is in \p s is flushed and then an unbuffered
+ * write of the contents of \p buf is performed.
+ */
 int buffer_putflush(buffer *s, const char *buf, ut32 len) {
 	if (!buffer_flush(s)) {
 		return 0;

librz/util/sdb/src/buffer.h

@@ -10,14 +10,20 @@
 extern "C" {
 #endif
 
+/**
+ * \brief The callback which writes to the file descriptor.
+ *
+ * Takes the parameters \c fd, \c buf, \c len in this order, and
+ * returns the number of bytes successfully written.
+ */
 typedef int (*BufferOp)(int, const char *, int);
 
 typedef struct buffer {
-	char *x;
-	unsigned int p;
-	unsigned int n;
-	int fd;
-	BufferOp op;
+	char *x; ///< The underlying memory buffer.
+	unsigned int p; ///< Anything between 0 and p is buffered; not yet written out.
+	unsigned int n; ///< The total size of the memory buffer.
+	int fd; ///< The file descriptor to write to when the buffer is full.
+	BufferOp op; ///< The callback which writes to the file descriptor.
 } buffer;
 
 extern void buffer_init(buffer *, BufferOp, int, char *, unsigned int);