Merge branch 'lukeshu/docs'

7 files changed, 73 insertions, 54 deletions

diff --git a/lib9p/CMakeLists.txt b/lib9p/CMakeLists.txt
index 2f5fc70..b356288 100644
--- a/lib9p/CMakeLists.txt
+++ b/lib9p/CMakeLists.txt
@@ -1,4 +1,4 @@
-# lib9p/CMakeLists.txt - TODO
+# lib9p/CMakeLists.txt - A 9P protocol and server library
 #
 # Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
diff --git a/lib9p/include/lib9p/9p.h b/lib9p/include/lib9p/9p.h
index f743afb..7724fc8 100644
--- a/lib9p/include/lib9p/9p.h
+++ b/lib9p/include/lib9p/9p.h
@@ -63,7 +63,7 @@ int lib9p_errorf(struct lib9p_ctx *ctx, uint32_t linux_errno, char const *fmt, .
 /* main T-message functions ***************************************************/
 
 /**
- * Validate a message's structure; it's size, string encodings, enums,
+ * Validate a message's structure; its size, string encodings, enums,
  * and bitfields.
  *
  * Return how much space the message will take when unmarshaled.  This
@@ -91,13 +91,10 @@ ssize_t lib9p_Tmsg_validate(struct lib9p_ctx *ctx, uint8_t *net_bytes);
 /**
  * Unmarshal the 9P message `net_bytes` into the C struct `ret_body`.
  *
- * Emits an error (return 0, set ctx->err_num and ctx->err_msg) if a
- * string contains invalid UTF-8 or a nul-byte.
- *
- * lib9p_unmarshal does no validation; you must run
+ * lib9p_Tmsg_unmarshal does no validation; you must run
  * lib9p_Tmsg_validate() first.
  *
- * @param ctx : negotiated protocol parameters, where to record errors
+ * @param ctx : negotiated protocol parameters
  * @param net_bytes : the complete message, starting with the "size[4]"
  *
  * @return ret_typ : the mesage type
@@ -152,17 +149,27 @@ static inline void lib9p_stat_assert(struct lib9p_stat stat) {
 }
 
 /**
- * TODO
+ * Validate a message's `stat` structure.
+ *
+ * @param ctx : negotiated protocol parameters, where to record errors
+ * @param net_bytes : network-encoded stat structure
+ * @param net_size : the number of net_bytes that may be read
  *
- * @return ret_net_size: number of bytes consumed; <=net_size
- * @return ret_host_size: number of bytes that lib9p_stat_unmarshal would take
+ * @return ret_net_size : number of bytes consumed; <=net_size
+ * @return ret_host_size : number of bytes that lib9p_stat_unmarshal would take
  * @return whether there was an error
  */
 bool lib9p_stat_validate(struct lib9p_ctx *ctx, uint32_t net_size, uint8_t *net_bytes,
                             uint32_t *ret_net_size, ssize_t *ret_host_size);
 
 /**
- * TODO
+ * Unmarshal the 9P `net_bytes` into the C struct `ret_obj`.
+ *
+ * lib9p_stat_unmarshal does no validation; you must run
+ * lib9p_stat_validate() first.
+ *
+ * @param ctx : negotiated protocol parameters
+ * @param net_bytes : network-encoded stat structure
  *
  * @return ret_obj : where to put the stat object itself
  * @return ret_extra : where to put strings for the stat object
@@ -172,8 +179,22 @@ uint32_t lib9p_stat_unmarshal(struct lib9p_ctx *ctx, uint8_t *net_bytes,
                               struct lib9p_stat *ret_obj, void *ret_extra);
 
 /**
+ * Marhsal a `struct lib9p_stat` structure into a byte-array.
+ *
+ * lib9p_Tmsg_marshal does no validation; it trusts that the
+ * programmer won't give it garbage input.  However, just as it
+ * doesn't marshal struct fields that aren't in ctx->version, it won't
+ * marshal bitfield bits that aren't in ctx->version; it applies a
+ * version-specific mask to bitfields.
+ *
+ * @param ctx : negotiated protocol parameters, where to record errors
+ * @param max_net_size : the maximum network-encoded size to allow
+ * @param obj : the message to encode
+ *
  * @return ret_bytes: the buffer to encode into
  * @return the number of bytes written, or 0 if the stat object does not fit in max_net_size
+ *
+ * @errno LINUX_ERANGE: reply does not fit in max_net_size
  */
 uint32_t lib9p_stat_marshal(struct lib9p_ctx *ctx, uint32_t max_net_size, struct lib9p_stat *obj,
                             uint8_t *ret_bytes);
diff --git a/lib9p/internal.h b/lib9p/internal.h
index 1f4975f..801dc4c 100644
--- a/lib9p/internal.h
+++ b/lib9p/internal.h
@@ -1,4 +1,4 @@
-/* lib9p/internal.h - TODO
+/* lib9p/internal.h - Internal machinery shared between parts of lib9p
  *
  * Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>
  * SPDX-License-Identifier: AGPL-3.0-or-later
diff --git a/lib9p/tests/runtest b/lib9p/tests/runtest
index 0966000..c2f6c41 100755
--- a/lib9p/tests/runtest
+++ b/lib9p/tests/runtest
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# lib9p/tests/runtest - TODO
+# lib9p/tests/runtest - Simple tests for the 9P `test_server`
 #
 # Copyright (C) 2025  Luke T. Shumaker <lukeshu@lukeshu.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
@@ -25,25 +25,37 @@ while [[ -d /proc/$server_pid && "$(readlink /proc/$server_pid/fd/4 2>/dev/null)
 
 out=$("${client[@]}" ls -l '')
 expect_lines \
-	'd-r-xr-xr-x M 0 root root  0 Oct  7 15:51 Documentation' \
-	'--r--r--r-- M 0 root root 14 Oct  7 15:51 README.md' \
-	'---w--w--w- M 0 root root  0 Oct  7 15:51 shutdown'
+	'd-r-xr-xr-x M 0 root root   0 Oct  7 15:51 Documentation' \
+	'--r--r--r-- M 0 root root 166 Oct  7 15:51 README.md' \
+	'---w--w--w- M 0 root root   0 Oct  7 15:51 shutdown'
 
 out=$("${client[@]}" ls -l 'Documentation/')
 expect_lines \
-	'--r--r--r-- M 0 root root 4 Oct  7 15:51 x'
+	'--r--r--r-- M 0 root root 162 Oct  7 15:51 x'
 
 out=$("${client[@]}" read 'README.md')
 expect_lines \
+	'<!--' \
+	'  README.md - test static file' \
+	'' \
+	'  Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>' \
+	'  SPDX-License-Identifier: AGPL-3.0-or-later' \
+	'-->' \
 	'Hello, world!'
 
 out=$("${client[@]}" read 'Documentation/x')
 expect_lines \
+	'<!--' \
+	'  Documentation/x - test static file' \
+	'' \
+	'  Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>' \
+	'  SPDX-License-Identifier: AGPL-3.0-or-later' \
+	'-->' \
 	'foo'
 
 out=$("${client[@]}" stat 'Documentation/x')
 expect_lines \
-	"'x' 'root' 'root' 'root' q (0000000000000001 1 ) m 0444 at 1728337905 mt 1728337904 l 4 t 0 d 0"
+	"'x' 'root' 'root' 'root' q (0000000000000001 1 ) m 0444 at 1728337905 mt 1728337904 l 162 t 0 d 0"
 
 out=$("${client[@]}" write 'shutdown' <<<1)
 expect_lines ''
diff --git a/lib9p/tests/test_server/main.c b/lib9p/tests/test_server/main.c
index 2c64cd4..c60dd71 100644
--- a/lib9p/tests/test_server/main.c
+++ b/lib9p/tests/test_server/main.c
@@ -73,8 +73,8 @@ static struct lib9p_stat api_stat(struct api_file *self, struct lib9p_srv_ctx *c
 		.kern_dev                 = 0,
 		.file_qid                 = api_qid(self),
 		.file_mode                = 0222,
-		.file_atime               = 1728337905,
-		.file_mtime               = 1728337904,
+		.file_atime               = UTIL9P_ATIME,
+		.file_mtime               = UTIL9P_MTIME,
 		.file_size                = 0,
 		.file_name                = lib9p_str("shutdown"),
 		.file_owner_uid           = lib9p_str("root"),
@@ -113,45 +113,19 @@ static uint32_t api_pread(struct api_file *, struct lib9p_srv_ctx *, void *, uin
 	assert_notreached("not readable");
 }
 
-/* file tree ******************************************************************/
+#define lo_box_api_as_lib9p_srv_file(obj) util9p_box(api, obj)
 
-#define _box(nam, obj) \
-	((struct lib9p_srv_file){                                    \
-		.self = obj,                                        \
-		.vtable = (void*)&_lo_##nam##_lib9p_srv_file_vtable, \
-	})
-#define lo_box_util9p_static_file_as_lib9p_srv_file(obj) _box(util9p_static_file, obj)
-#define lo_box_util9p_static_dir_as_lib9p_srv_file(obj)  _box(util9p_static_dir, obj)
-#define lo_box_api_as_lib9p_srv_file(obj)                _box(api, obj)
+/* file tree ******************************************************************/
 
 enum { PATH_BASE = __COUNTER__ };
 #define PATH_COUNTER __COUNTER__ - PATH_BASE
 
-#define STATIC_COMMON(STRNAME, MODE)                                      \
-	{                                                                 \
-		.u_name = "root", .u_num = 0, /* owner user */            \
-		.g_name = "root", .g_num = 0, /* owner group */           \
-		.m_name = "root", .m_num = 0, /* last-modified-by user */ \
-		                                                          \
-		.pathnum = PATH_COUNTER,                                  \
-		.name    = STRNAME,                                       \
-		.perm    = MODE,                                          \
-		.atime   = 1728337905,                                    \
-		.mtime   = 1728337904,                                    \
-	}
-
-#define STATIC_FILE(STRNAME, SYMNAME)                                              \
-	lo_box_util9p_static_file_as_lib9p_srv_file(&((struct util9p_static_file){ \
-		._util9p_static_common = STATIC_COMMON(STRNAME, 0444),             \
-		.data_start            = _binary_static_##SYMNAME##_start,         \
-		.data_end              = _binary_static_##SYMNAME##_end,           \
-	}))
-
-#define STATIC_DIR(STRNAME, ...)                                                  \
-	lo_box_util9p_static_dir_as_lib9p_srv_file(&((struct util9p_static_dir){  \
-		._util9p_static_common = STATIC_COMMON(STRNAME, 0555),            \
-		.members = { __VA_ARGS__ LO_NULL(lib9p_srv_file) },               \
-	}))
+#define STATIC_FILE(STRNAME, SYMNAME)                                      \
+	UTIL9P_STATIC_FILE(PATH_COUNTER, STRNAME,                          \
+	                   .data_start = _binary_static_##SYMNAME##_start, \
+	                   .data_end   = _binary_static_##SYMNAME##_end)
+#define STATIC_DIR(STRNAME, ...)  \
+	UTIL9P_STATIC_DIR(PATH_COUNTER, STRNAME, __VA_ARGS__)
 
 struct lib9p_srv_file root =
 		STATIC_DIR("",
diff --git a/lib9p/tests/test_server/static/Documentation/x b/lib9p/tests/test_server/static/Documentation/x
index 257cc56..b9b08d4 100644
--- a/lib9p/tests/test_server/static/Documentation/x
+++ b/lib9p/tests/test_server/static/Documentation/x
@@ -1 +1,7 @@
+<!--
+  Documentation/x - test static file
+
+  Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>
+  SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 foo
diff --git a/lib9p/tests/test_server/static/README.md b/lib9p/tests/test_server/static/README.md
index af5626b..c2d88ed 100644
--- a/lib9p/tests/test_server/static/README.md
+++ b/lib9p/tests/test_server/static/README.md
@@ -1 +1,7 @@
+<!--
+  README.md - test static file
+
+  Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>
+  SPDX-License-Identifier: AGPL-3.0-or-later
+-->
 Hello, world!