i dunno if this makes things clearer or not

ui/ui_darwin.go

@@ -23,7 +23,7 @@ func Desktop() UI {
 	}
 
 	log.Println("Creating new Cocoa UI")
-	C.initialize()
+	C.ui_init()
 	desktopUI = new(cocoaUI)
 	return desktopUI
 }
@@ -38,7 +38,7 @@ func (ui *cocoaUI) Run(out chan events.UserEvent, in chan events.BackgroundEvent
 	ui.in = in
 	ui.out = out
 	go ui.forwardEvents()
-	C.run()
+	C.ui_run()
 	return nil
 }
 
@@ -46,12 +46,12 @@ func (ui *cocoaUI) forwardEvent(e events.BackgroundEvent) {
 	switch v := e.(type) {
 	case events.SigIntEvent:
 		log.Println("Cocoa UI sees sig int, forwarding to NSApp")
-		C.shutdown()
+		C.bg_shutdown()
 
 	case events.SetRootEvent:
 		cpath := C.CString(v.Path)
 		defer C.free(unsafe.Pointer(cpath))
-		C.set_root(cpath)
+		C.bg_set_root(cpath)
 
 	case events.BeginRequestEvent:
 		cpath := C.CString(v.Path)
@@ -62,10 +62,10 @@ func (ui *cocoaUI) forwardEvent(e events.BackgroundEvent) {
 			path: cpath,
 		}
 
-		C.received_request(req)
+		C.bg_received_request(req)
 
 	case events.EndRequestEvent:
-		C.sent_response(&C.struct_ResponseMeta{
+		C.bg_sent_response(&C.struct_ResponseMeta{
 			seq:    C.int(v.Seq),
 			status: C.int(v.Status),
 			bytes:  C.int(v.Bytes),

ui/ui_darwin.h

@@ -1,21 +1,45 @@
+// RequestMeta contains metadata about an http request as received by the http
+// server
 struct RequestMeta {
+	// seq is a request identifier that can be used to relate incoming requests
+	// to outgoing responses.
 	int seq;
 	char *path;
 };
 
 typedef struct RequestMeta RequestMeta;
 
+// ResponseMeta contains metadata about an http request as sent by the http
+// server
 struct ResponseMeta {
-	int seq;
-	int status;
-	int bytes;
+	int seq;    // same id as the originating request
+	int status; // http status code
+	int bytes;  // number of bytes written in the response
 };
 
 typedef struct ResponseMeta ResponseMeta;
 
-void initialize();
-int run();
-void shutdown();
-void set_root(char *);
-void received_request(RequestMeta *);
-void sent_response(ResponseMeta *);
+// the Go backend calls initialize to allow the frontend to perform any up
+// front allocations or reserve any resources it might need.
+void ui_init();
+
+// the Go backend calls run to start the front end's main event loop. this
+// function is expected to block until the front end is done and the
+// application is ready to terminate.
+int ui_run();
+
+// shutdown is provided to allow the Go backend to signal to the frontend that
+// it believes the program should be shut down for some reason outside of user
+// interaction.
+void bg_shutdown();
+
+// set_root informs the front end that the webserver has set its root directory
+void bg_set_root(char *);
+
+// received_request informs the front end that the webserver has received an
+// http request.
+void bg_received_request(RequestMeta *);
+
+// sent_response informs the front end that the webserver has completed serving
+// a response.
+void bg_sent_response(ResponseMeta *);

ui/ui_darwin.m

@@ -6,34 +6,34 @@
 id defaultAutoreleasePool;
 id appDelegate;
 
-void initialize() {
+void ui_init() {
     defaultAutoreleasePool = [NSAutoreleasePool new];
     [NSApplication sharedApplication];
     [NSApp setDelegate: [[AppDelegate new] autorelease]];
     [NSApp setActivationPolicy:NSApplicationActivationPolicyRegular];
 }
 
-int run() {
+int ui_run() {
     [NSApp run];
     [defaultAutoreleasePool drain];
     return 0;
 }
 
-void shutdown() {
+void bg_shutdown() {
 	[[NSApplication sharedApplication] terminate:nil];
 }
 
-void set_root(char *path) {
+void bg_set_root(char *path) {
 	id listener = [[EventBridge shared] listener];
 	[listener serverDidSetRoot:[NSString stringWithUTF8String:path]];
 }
 
-void received_request(RequestMeta *meta) {
+void bg_received_request(RequestMeta *meta) {
 	id listener = [[EventBridge shared] listener];
 	[listener serverDidReceiveRequest:meta];
 }
 
-void sent_response(ResponseMeta *meta) {
+void bg_sent_response(ResponseMeta *meta) {
 	id listener = [[EventBridge shared] listener];
 	[listener serverDidWriteResponse:meta];
 }