From d0509d719c27d95b5d0f8379d66f13b99b60c42e Mon Sep 17 00:00:00 2001
From: Christian Poveda <christianpoveda@protonmail.com>
Date: Tue, 1 Oct 2019 10:31:04 -0500
Subject: [PATCH] Add docs for helper functions

---
 src/shims/io.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/src/shims/io.rs b/src/shims/io.rs
index c91d3a07726..0d1adcce652 100644
--- a/src/shims/io.rs
+++ b/src/shims/io.rs
@@ -151,6 +151,14 @@ fn read(
         )
     }
 
+    /// Helper function that gets a `FileHandle` immutable reference and allows to manipulate it
+    /// using `f`.
+    ///
+    /// If the `fd` file descriptor does not corresponds to a file, this functions returns `Ok(-1)`
+    /// and sets `Evaluator::last_error` to `libc::EBADF` (invalid file descriptor).
+    ///
+    /// This function uses `T: From<i32>` instead of `i32` directly because some IO related
+    /// functions return different integer types (like `read`, that returns an `i64`)
     fn get_handle_and<F, T: From<i32>>(&mut self, fd: i32, f: F) -> InterpResult<'tcx, T>
     where
         F: Fn(&FileHandle) -> InterpResult<'tcx, T>,
@@ -164,6 +172,16 @@ fn get_handle_and<F, T: From<i32>>(&mut self, fd: i32, f: F) -> InterpResult<'tc
         }
     }
 
+    /// Helper function that removes a `FileHandle` and allows to manipulate it using the `f`
+    /// closure. This function is quite useful when you need to modify a `FileHandle` but you need
+    /// to modify `MiriEvalContext` at the same time, so you can modify the handle and reinsert it
+    /// using `f`.
+    ///
+    /// If the `fd` file descriptor does not corresponds to a file, this functions returns `Ok(-1)`
+    /// and sets `Evaluator::last_error` to `libc::EBADF` (invalid file descriptor).
+    ///
+    /// This function uses `T: From<i32>` instead of `i32` directly because some IO related
+    /// functions return different integer types (like `read`, that returns an `i64`)
     fn remove_handle_and<F, T: From<i32>>(&mut self, fd: i32, mut f: F) -> InterpResult<'tcx, T>
     where
         F: FnMut(FileHandle, &mut MiriEvalContext<'mir, 'tcx>) -> InterpResult<'tcx, T>,
@@ -177,6 +195,12 @@ fn remove_handle_and<F, T: From<i32>>(&mut self, fd: i32, mut f: F) -> InterpRes
         }
     }
 
+    /// Helper function that consumes an `std::io::Result<T>` and returns an
+    /// `InterpResult<'tcx,T>::Ok` instead. It is expected that the result can be converted to an
+    /// OS error using `std::io::Error::raw_os_error`.
+    ///
+    /// This function uses `T: From<i32>` instead of `i32` directly because some IO related
+    /// functions return different integer types (like `read`, that returns an `i64`)
     fn consume_result<T: From<i32>>(&mut self, result: std::io::Result<T>) -> InterpResult<'tcx, T> {
         match result {
             Ok(ok) => Ok(ok),
-- 
2.44.0