From dbbd727740db12249279a846575facb8967075e5 Mon Sep 17 00:00:00 2001
From: Drew DeVault <sir@cmpwn.com>
Date: Sat, 11 Mar 2023 13:48:35 +0100
Subject: [PATCH] gen: generate some doc comments

---
 gen/client.ha |  6 ++++--
 gen/server.ha | 16 +++++++++++-----
 gen/shared.ha |  3 ++-
 3 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/gen/client.ha b/gen/client.ha
index e0fe620..df0b2d3 100644
--- a/gen/client.ha
+++ b/gen/client.ha
@@ -23,6 +23,7 @@ export fn client(out: io::handle, doc: *ast::document) (void | io::error) = {
 	};
 };
 
+// TODO: Generate docs for these members
 const c_iface_method_src: str =
 	`export fn $iface_$method(
 	ep: helios::cap,$cparams$mparams
@@ -54,10 +55,11 @@ fn c_iface(
 	defer free(id);
 	const hash = genhash(&id);
 
-	fmt::fprintfln(out, "def {}_ID: u32 = 0x{:X};\n", name, hash)!;
+	fmt::fprintfln(out, "// ID for the {} IPC interface.", iface.name)?;
+	fmt::fprintfln(out, "export def {}_ID: u32 = 0x{:X};\n", name, hash)?;
 
 	iface_label(out, iface, name)?;
-	fmt::fprintln(out)!;
+	fmt::fprintln(out)?;
 
 	for (let i = 0z; i < len(iface.methods); i += 1) {
 		c_meth(out, iface, &iface.methods[i])?;
diff --git a/gen/server.ha b/gen/server.ha
index 86ef9e2..9b52cb8 100644
--- a/gen/server.ha
+++ b/gen/server.ha
@@ -26,7 +26,8 @@ export fn server(out: io::handle, doc: *ast::document) (void | io::error) = {
 };
 
 const s_iface_header_src: str =
-	`export type $iface_iface = struct {`;
+	`// Implementation of a [[$iface]] object.
+export type $iface_iface = struct {`;
 let st_iface_header: tmpl::template = [];
 
 const s_iface_method_src: str =
@@ -52,7 +53,8 @@ fn s_iface(
 	defer free(id);
 	const hash = genhash(&id);
 
-	fmt::fprintfln(out, "def {}_ID: u32 = 0x{:X};\n", name, hash)!;
+	fmt::fprintfln(out, "// ID for the {} IPC interface.", iface.name)?;
+	fmt::fprintfln(out, "export def {}_ID: u32 = 0x{:X};\n", name, hash)?;
 
 	for (let i = 0z; i < len(iface.methods); i += 1) {
 		const meth = &iface.methods[i];
@@ -87,7 +89,8 @@ fn s_iface(
 };
 
 const s_method_fntype_src: str =
-	`export type fn_$iface_$method = fn(object: *$object${caps_in}$params) $result;`;
+	`// Implementation callback for $iface::$method; see [[${iface}_iface]].
+export type fn_$iface_$method = fn(object: *$object${caps_in}$params) $result;`;
 let st_method_fntype: tmpl::template = [];
 
 @init fn s_method_fntype() void = {
@@ -156,7 +159,9 @@ fn s_method_fntype(
 	fmt::fprintln(out)?;
 };
 
-const s_iface_object_src: str = `export type $iface = struct {
+const s_iface_object_src: str = `// Instance of an $iface object. Users may subtype this object to add
+// instance-specific state.
+export type $iface = struct {
 	_iface: *$iface_iface,
 	_endpoint: helios::cap,
 };`;
@@ -176,7 +181,8 @@ fn s_iface_object(
 	fmt::fprintln(out)!;
 };
 
-const s_iface_dispatch_header_src: str = `export fn $iface_dispatch(
+const s_iface_dispatch_header_src: str = `// Dispatches a recv operation for an [[$iface]] object
+export fn $iface_dispatch(
 	object: *$iface,
 ) void = {
 	rt::ipcbuf.tag = ${max_cap} << 8;
diff --git a/gen/shared.ha b/gen/shared.ha
index d60d3a9..0cf0c37 100644
--- a/gen/shared.ha
+++ b/gen/shared.ha
@@ -3,7 +3,8 @@ use fmt;
 use io;
 use tmpl = strings::template;
 
-const iface_label_src: str = `export type $iface_label = enum u64 {
+const iface_label_src: str = `// Labels for operations against $iface objects.
+export type $iface_label = enum u64 {
 `;
 let t_iface_label: tmpl::template = [];
 
-- 
2.38.5