document the cvt methods

Author: the8472

library/std/src/sys/pal/unix/mod.rs

@@ -307,10 +307,13 @@ macro_rules! impl_is_minus_one {
 
 impl_is_minus_one!{i8i16i32i64isize}
 
+/// Convert native return values to Result using the *-1 means error is in `errno`* convention.
+/// Non-error values are `Ok`-wrapped.
 pubfncvt<T:IsMinusOne>(t:T) -> crate::io::Result<T>{
 if t.is_minus_one(){Err(crate::io::Error::last_os_error())}else{Ok(t)}
 }
 
+/// `-1` → look at `errno` → retry on `EINTR`. Otherwise `Ok()`-wrap the closure return value.
 pubfncvt_r<T,F>(mutf:F) -> crate::io::Result<T>
 where
 T:IsMinusOne,
@@ -325,6 +328,7 @@ where
 }
 
 #[allow(dead_code)]// Not used on all platforms.
+/// Zero means `Ok()`, all other values are treated as raw OS errors. Does not look at `errno`.
 pubfncvt_nz(error: libc::c_int) -> crate::io::Result<()>{
 if error == 0{Ok(())}else{Err(crate::io::Error::from_raw_os_error(error))}
 }