diff --git a/include/os.h b/include/os.h
index 54874f5e0e..0415f0f0e7 100644
--- a/include/os.h
+++ b/include/os.h
@@ -110,6 +110,10 @@ void os_exit(int exit_code) __attribute__((noreturn));
 
 /**
  * os_alarm() - access to the OS alarm() system call
+ *
+ * @seconds: number of seconds before the signal is sent
+ * Returns: number of seconds remaining until any previously scheduled alarm was
+ * due to be delivered; 0 if there was no previously scheduled alarm
  */
 unsigned int os_alarm(unsigned int seconds);