From e8c4f5f36537c236820857168e66bc07dae2846e Mon Sep 17 00:00:00 2001
From: Hoël Bézier <hoelbezier@riseup.net>
Date: Wed, 17 Dec 2025 23:38:32 +0100
Subject: add buffer.h documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Hoël Bézier <hoelbezier@riseup.net>
---
 doc/libstddjb/buffer.html | 67 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 65 insertions(+), 2 deletions(-)

(limited to 'doc')

diff --git a/doc/libstddjb/buffer.html b/doc/libstddjb/buffer.html
index 3cc4112..000e0e3 100644
--- a/doc/libstddjb/buffer.html
+++ b/doc/libstddjb/buffer.html
@@ -18,10 +18,73 @@
 <a href="//skarnet.org/">skarnet.org</a>
 </p>
 
-<h1> The <tt>skalibs/buffer.h</tt> header </h1>
+<h1> The <tt>buffer</tt> library interface </h1>
 
 <p>
- TODO: write this documentation page. (Sorry!)
+ The following functions are declared in the <tt>skalibs/buffer.h<tt> header,
+and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
+</p>
+
+<h2> General information </h2>
+
+<p>
+ skalibs provides convenience structures and functions to perform buffered I/O.
+These structures and functions abstract and replace, from a programer’s point
+of vue, direct calls to fd_read or fd_write for instance.
+</p>
+
+<p>
+ A buffer is a structure containing the following fields:
+</p>
+
+<ul>
+ <li> <em>op</em>: a pointer to a function performing I/O. This is the function
+that will be called anytime the buffer needs to acquire (or flush) data to its
+underlying fd. </li>
+ <li> <em>fd</em>: the fd from which data will be read or written. </li>
+ <li> <em>c</em>: a circular buffer used to store data. </li>
+</ul>
+
+<p>
+ Users should not need to interact directly with any of these fields. They are
+initialized by <tt>buffer_init</tt> or <tt>BUFFER_INIT</tt>. Ulterior
+interactions with the buffer should only be done with the various dedicated
+functions.
+</p>
+
+<h2> Functions </h2>
+
+<p>
+<code> ssize_t buffer_put (buffer *b, char const *buf, size_t len) </code> <br />
+Write the <em>len</em> bytes pointed to by <em>buf</em> to buffer <em>b</em>.
+Returns the number of bytes written if it succeeds, or -1 and sets errno if it
+fails.
+</p>
+
+<p>
+<code> ssize_t buffer_puts (buffer *b, char const *s) </code> <br />
+Write the string <em>s</em>, terminating nul-byte excepted, to buffer <em>b</em>.
+Returns the number of bytes written if it succeeds, or -1 and sets errno if it
+fails.
+</p>
+
+<p>
+<code> int buffer_flush(buffer *b) </code> <br />
+Flushes the buffer <em>b</em>.
+Returns 1 if it succeeds, 0 and sets errno if it fails.
+</p>
+
+<p>
+<code> ssize_t buffer_get (buffer *b, char *s, size_t len) </code> <br />
+Read <em>len</em> bytes from buffer <em>b</em> and write them into <em>s</em>.
+Retuns the number of bytes read if it succeeds, or -1 and sets errno if it
+fails.
+</p>
+
+<p>
+ The above are the most important and fundamental functions for buffering.
+Other functions can be found in the same header and their prototypes are
+self-explaining.
 </p>
 
 </body>
-- 
cgit v1.3.1