docs: improve documentation

runtime/src/global_request_scheduler.c

@@ -28,7 +28,8 @@ global_request_scheduler_add(sandbox_request_t *sandbox_request)
 
 /**
  * Removes a sandbox request according to the scheduling policy of the variant
- * @returns pointer to a sandbox request
+ * @param removed_sandbox where to write the adddress of the removed sandbox
+ * @returns 0 if successful, -1 if empty, -2 if unable to take lock or perform atomic operation
  */
 int
 global_request_scheduler_remove(sandbox_request_t **removed_sandbox)

runtime/src/local_runqueue_list.c

@@ -43,6 +43,7 @@ local_runqueue_list_remove_and_return()
 struct sandbox *
 local_runqueue_list_get_next()
 {
+	// If our local runqueue is empty, try to pull and allocate a sandbox request from the global request scheduler
 	if (local_runqueue_is_empty()) {
 		sandbox_request_t *sandbox_request;