diff --git a/inc/vmapi/hf/call.h b/inc/vmapi/hf/call.h
index 771997a..ac1ddff 100644
--- a/inc/vmapi/hf/call.h
+++ b/inc/vmapi/hf/call.h
@@ -44,6 +44,8 @@
 
 /**
  * Runs the given vcpu of the given vm.
+ *
+ * Returns an hf_vcpu_run_return struct telling the scheduler what to do next.
  */
 static inline struct hf_vcpu_run_return hf_vcpu_run(uint32_t vm_id,
 						    uint32_t vcpu_idx)
@@ -71,6 +73,8 @@
 /**
  * Configures the pages to send/receive data through. The pages must not be
  * shared.
+ *
+ * Returns 0 on success or -1 or failure.
  */
 static inline int64_t hf_vm_configure(hf_ipaddr_t send, hf_ipaddr_t recv)
 {
@@ -79,6 +83,11 @@
 
 /**
  * Copies data from the sender's send buffer to the recipient's receive buffer.
+ *
+ * Returns -1 on failure, and on success either:
+ * - 0, if the caller is a secondary VM
+ * - the ID of the vCPU to run to receive the message, if the caller is the
+ * primary VM.
  */
 static inline int64_t hf_mailbox_send(uint32_t vm_id, size_t size)
 {
@@ -100,7 +109,10 @@
 }
 
 /**
- * Clears the mailbox so a new message can be received.
+ * Clears the caller's mailbox so a new message can be received.
+ *
+ * Returns 0 on success, or -1 if the mailbox hasn't been read or is already
+ * empty.
  */
 static inline int64_t hf_mailbox_clear(void)
 {