From 4c745dab4c6925fa17714c2214ed5941e5cbf64d Mon Sep 17 00:00:00 2001
From: Mattias Andrée <m@maandree.se>
Date: Thu, 20 Feb 2025 20:24:28 +0100
Subject: Validate unmarshalled state + add man pages for (un)marshal functions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Mattias Andrée <m@maandree.se>
---
 common.h | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 88 insertions(+), 1 deletion(-)

(limited to 'common.h')

diff --git a/common.h b/common.h
index a1c385f..11d0d6b 100644
--- a/common.h
+++ b/common.h
@@ -5,6 +5,7 @@
 #include <ctype.h>
 #include <errno.h>
 #include <limits.h>
+#include <stdint.h>
 #include <string.h>
 #include <unistd.h>
 
@@ -143,14 +144,100 @@ HIDDEN void libterminput_parse_sequence__(union libterminput_input *input, struc
  */
 HIDDEN int libterminput_read_symbol__(int fd, struct input *input, struct libterminput_state *ctx);
 
-/* TODO doc, test */
+/**
+ * Marshal the parsed input
+ * 
+ * @param   how   Object used to store the serialization
+ * @param   what  The input to marshal
+ * @return        0 on success, -1 on failure
+ * 
+ * This function will fail for any reason `*how->store` fails
+ */
 HIDDEN int libterminput_marshal_keypress__(struct libterminput_marshaller *how, const struct libterminput_keypress *what);
+
+/**
+ * Marshal the parsed input
+ * 
+ * @param   how   Object used to store the serialization
+ * @param   what  The input to marshal
+ * @return        0 on success, -1 on failure
+ * 
+ * This function will fail for any reason `*how->store` fails
+ */
 HIDDEN int libterminput_marshal_text__(struct libterminput_marshaller *how, const struct libterminput_text *what);
+
+/**
+ * Marshal the parsed input
+ * 
+ * @param   how   Object used to store the serialization
+ * @param   what  The input to marshal
+ * @return        0 on success, -1 on failure
+ * 
+ * This function will fail for any reason `*how->store` fails
+ */
 HIDDEN int libterminput_marshal_mouseevent__(struct libterminput_marshaller *how, const struct libterminput_mouseevent *what);
+
+/**
+ * Marshal the parsed input
+ * 
+ * @param   how   Object used to store the serialization
+ * @param   what  The input to marshal
+ * @return        0 on success, -1 on failure
+ * 
+ * This function will fail for any reason `*how->store` fails
+ */
 HIDDEN int libterminput_marshal_position__(struct libterminput_marshaller *how, const struct libterminput_position *what);
+
+/**
+ * Unmarshal the parsed input
+ * 
+ * @param   how   Object used to load the serialization
+ * @param   what  Output parameter for the unmarshalled input
+ * @return        0 on success, -1 on failure
+ * 
+ * @throws  EINVAL  Invalid serialisation
+ * 
+ * This function will fail for any reason `*how->load` fails
+ */
 HIDDEN int libterminput_unmarshal_keypress__(struct libterminput_unmarshaller *how, struct libterminput_keypress *what);
+
+/**
+ * Unmarshal the parsed input
+ * 
+ * @param   how   Object used to load the serialization
+ * @param   what  Output parameter for the unmarshalled input
+ * @return        0 on success, -1 on failure
+ * 
+ * @throws  EINVAL  Invalid serialisation
+ * 
+ * This function will fail for any reason `*how->load` fails
+ */
 HIDDEN int libterminput_unmarshal_text__(struct libterminput_unmarshaller *how, struct libterminput_text *what);
+
+/**
+ * Unmarshal the parsed input
+ * 
+ * @param   how   Object used to load the serialization
+ * @param   what  Output parameter for the unmarshalled input
+ * @return        0 on success, -1 on failure
+ * 
+ * @throws  EINVAL  Invalid serialisation
+ * 
+ * This function will fail for any reason `*how->load` fails
+ */
 HIDDEN int libterminput_unmarshal_mouseevent__(struct libterminput_unmarshaller *how, struct libterminput_mouseevent *what);
+
+/**
+ * Unmarshal the parsed input
+ * 
+ * @param   how   Object used to load the serialization
+ * @param   what  Output parameter for the unmarshalled input
+ * @return        0 on success, -1 on failure
+ * 
+ * @throws  EINVAL  Invalid serialisation
+ * 
+ * This function will fail for any reason `*how->load` fails
+ */
 HIDDEN int libterminput_unmarshal_position__(struct libterminput_unmarshaller *how, struct libterminput_position *what);
 
 
-- 
cgit v1.2.3-70-g09d2