libs: doc comments

5 files changed, 36 insertions, 29 deletions

diff --git a/src/libstd/sys/sgx/abi/thread.rs b/src/libstd/sys/sgx/abi/thread.rs
index 588fbcd9d43..86fe09d0035 100644
--- a/src/libstd/sys/sgx/abi/thread.rs
+++ b/src/libstd/sys/sgx/abi/thread.rs
@@ -1,6 +1,6 @@
 use fortanix_sgx_abi::Tcs;
 
-/// Get the ID for the current thread. The ID is guaranteed to be unique among
+/// Gets the ID for the current thread. The ID is guaranteed to be unique among
 /// all currently running threads in the enclave, and it is guaranteed to be
 /// constant for the lifetime of the thread. More specifically for SGX, there
 /// is a one-to-one correspondence of the ID to the address of the TCS.
diff --git a/src/libstd/sys/sgx/abi/tls.rs b/src/libstd/sys/sgx/abi/tls.rs
index b8e09d58deb..e1fc3696845 100644
--- a/src/libstd/sys/sgx/abi/tls.rs
+++ b/src/libstd/sys/sgx/abi/tls.rs
@@ -182,7 +182,7 @@ mod sync_bitset {
             self.0[hi].fetch_and(!lo, Ordering::Relaxed);
         }
 
-        /// Set any unset bit. Not atomic. Returns `None` if all bits were
+        /// Sets any unset bit. Not atomic. Returns `None` if all bits were
         /// observed to be set.
         pub fn set(&self) -> Option<usize> {
             'elems: for (idx, elem) in self.0.iter().enumerate() {
diff --git a/src/libstd/sys/sgx/abi/usercalls/alloc.rs b/src/libstd/sys/sgx/abi/usercalls/alloc.rs
index 2efbaa9b148..0ccbbbc6501 100644
--- a/src/libstd/sys/sgx/abi/usercalls/alloc.rs
+++ b/src/libstd/sys/sgx/abi/usercalls/alloc.rs
@@ -63,44 +63,49 @@ pub unsafe trait UserSafe {
 
     /// Construct a pointer to `Self` given a memory range in user space.
     ///
-    /// NB. This takes a size, not a length!
+    /// N.B., this takes a size, not a length!
     ///
     /// # Safety
+    ///
     /// The caller must ensure the memory range is in user memory, is the
     /// correct size and is correctly aligned and points to the right type.
     unsafe fn from_raw_sized_unchecked(ptr: *mut u8, size: usize) -> *mut Self;
 
     /// Construct a pointer to `Self` given a memory range.
     ///
-    /// NB. This takes a size, not a length!
+    /// N.B., this takes a size, not a length!
     ///
     /// # Safety
+    ///
     /// The caller must ensure the memory range points to the correct type.
     ///
     /// # Panics
+    ///
     /// This function panics if:
     ///
-    /// * The pointer is not aligned
-    /// * The pointer is null
-    /// * The pointed-to range is not in user memory
+    /// * the pointer is not aligned.
+    /// * the pointer is null.
+    /// * the pointed-to range is not in user memory.
     unsafe fn from_raw_sized(ptr: *mut u8, size: usize) -> NonNull<Self> {
         let ret = Self::from_raw_sized_unchecked(ptr, size);
         Self::check_ptr(ret);
         NonNull::new_unchecked(ret as _)
     }
 
-    /// Check if a pointer may point to Self in user memory.
+    /// Checks if a pointer may point to `Self` in user memory.
     ///
     /// # Safety
+    ///
     /// The caller must ensure the memory range points to the correct type and
     /// length (if this is a slice).
     ///
     /// # Panics
+    ///
     /// This function panics if:
     ///
-    /// * The pointer is not aligned
-    /// * The pointer is null
-    /// * The pointed-to range is not in user memory
+    /// * the pointer is not aligned.
+    /// * the pointer is null.
+    /// * the pointed-to range is not in user memory.
     unsafe fn check_ptr(ptr: *const Self) {
         let is_aligned = |p| -> bool {
             0 == (p as usize) & (Self::align_of() - 1)
@@ -188,7 +193,7 @@ impl<T: ?Sized> User<T> where T: UserSafe {
         }
     }
 
-    /// Copy `val` into freshly allocated space in user memory.
+    /// Copies `val` into freshly allocated space in user memory.
     pub fn new_from_enclave(val: &T) -> Self {
         unsafe {
             let ret = Self::new_uninit_bytes(mem::size_of_val(val));
@@ -201,7 +206,7 @@ impl<T: ?Sized> User<T> where T: UserSafe {
         }
     }
 
-    /// Create an owned `User<T>` from a raw pointer.
+    /// Creates an owned `User<T>` from a raw pointer.
     ///
     /// # Safety
     /// The caller must ensure `ptr` points to `T`, is freeable with the `free`
@@ -218,7 +223,7 @@ impl<T: ?Sized> User<T> where T: UserSafe {
         User(NonNull::new_userref(ptr))
     }
 
-    /// Convert this value into a raw pointer. The value will no longer be
+    /// Converts this value into a raw pointer. The value will no longer be
     /// automatically freed.
     pub fn into_raw(self) -> *mut T {
         let ret = self.0;
@@ -242,7 +247,7 @@ impl<T> User<[T]> where [T]: UserSafe {
         Self::new_uninit_bytes(n * mem::size_of::<T>())
     }
 
-    /// Create an owned `User<[T]>` from a raw thin pointer and a slice length.
+    /// Creates an owned `User<[T]>` from a raw thin pointer and a slice length.
     ///
     /// # Safety
     /// The caller must ensure `ptr` points to `len` elements of `T`, is
@@ -262,7 +267,7 @@ impl<T> User<[T]> where [T]: UserSafe {
 
 #[unstable(feature = "sgx_platform", issue = "56975")]
 impl<T: ?Sized> UserRef<T> where T: UserSafe {
-    /// Create a `&UserRef<[T]>` from a raw pointer.
+    /// Creates a `&UserRef<[T]>` from a raw pointer.
     ///
     /// # Safety
     /// The caller must ensure `ptr` points to `T`.
@@ -278,7 +283,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe {
         &*(ptr as *const Self)
     }
 
-    /// Create a `&mut UserRef<[T]>` from a raw pointer. See the struct
+    /// Creates a `&mut UserRef<[T]>` from a raw pointer. See the struct
     /// documentation for the nuances regarding a `&mut UserRef<T>`.
     ///
     /// # Safety
@@ -295,7 +300,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe {
         &mut*(ptr as *mut Self)
     }
 
-    /// Copy `val` into user memory.
+    /// Copies `val` into user memory.
     ///
     /// # Panics
     /// This function panics if the destination doesn't have the same size as
@@ -311,7 +316,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe {
         }
     }
 
-    /// Copy the value from user memory and place it into `dest`.
+    /// Copies the value from user memory and place it into `dest`.
     ///
     /// # Panics
     /// This function panics if the destination doesn't have the same size as
@@ -340,7 +345,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe {
 
 #[unstable(feature = "sgx_platform", issue = "56975")]
 impl<T> UserRef<T> where T: UserSafe {
-    /// Copy the value from user memory into enclave memory.
+    /// Copies the value from user memory into enclave memory.
     pub fn to_enclave(&self) -> T {
         unsafe { ptr::read(self.0.get()) }
     }
@@ -348,7 +353,7 @@ impl<T> UserRef<T> where T: UserSafe {
 
 #[unstable(feature = "sgx_platform", issue = "56975")]
 impl<T> UserRef<[T]> where [T]: UserSafe {
-    /// Create a `&UserRef<[T]>` from a raw thin pointer and a slice length.
+    /// Creates a `&UserRef<[T]>` from a raw thin pointer and a slice length.
     ///
     /// # Safety
     /// The caller must ensure `ptr` points to `n` elements of `T`.
@@ -363,7 +368,7 @@ impl<T> UserRef<[T]> where [T]: UserSafe {
         &*(<[T]>::from_raw_sized(ptr as _, len * mem::size_of::<T>()).as_ptr() as *const Self)
     }
 
-    /// Create a `&mut UserRef<[T]>` from a raw thin pointer and a slice length.
+    /// Creates a `&mut UserRef<[T]>` from a raw thin pointer and a slice length.
     /// See the struct documentation for the nuances regarding a
     /// `&mut UserRef<T>`.
     ///
@@ -395,7 +400,7 @@ impl<T> UserRef<[T]> where [T]: UserSafe {
         unsafe { (*self.0.get()).len() }
     }
 
-    /// Copy the value from user memory and place it into `dest`. Afterwards,
+    /// Copies the value from user memory and place it into `dest`. Afterwards,
     /// `dest` will contain exactly `self.len()` elements.
     ///
     /// # Panics
@@ -411,7 +416,7 @@ impl<T> UserRef<[T]> where [T]: UserSafe {
         }
     }
 
-    /// Copy the value from user memory into a vector in enclave memory.
+    /// Copies the value from user memory into a vector in enclave memory.
     pub fn to_enclave(&self) -> Vec<T> {
         let mut ret = Vec::with_capacity(self.len());
         self.copy_to_enclave_vec(&mut ret);
@@ -526,7 +531,7 @@ impl<T, I: SliceIndex<[T]>> IndexMut<I> for UserRef<[T]> where [T]: UserSafe, I:
 
 #[unstable(feature = "sgx_platform", issue = "56975")]
 impl UserRef<super::raw::ByteBuffer> {
-    /// Copy the user memory range pointed to by the user `ByteBuffer` to
+    /// Copies the user memory range pointed to by the user `ByteBuffer` to
     /// enclave memory.
     ///
     /// # Panics
diff --git a/src/libstd/sys/sgx/abi/usercalls/raw.rs b/src/libstd/sys/sgx/abi/usercalls/raw.rs
index 27f780ca224..004cf57602b 100644
--- a/src/libstd/sys/sgx/abi/usercalls/raw.rs
+++ b/src/libstd/sys/sgx/abi/usercalls/raw.rs
@@ -12,14 +12,16 @@ extern "C" {
     fn usercall(nr: u64, p1: u64, p2: u64, _ignore: u64, p3: u64, p4: u64) -> UsercallReturn;
 }
 
-/// Perform the raw usercall operation as defined in the ABI calling convention.
+/// Performs the raw usercall operation as defined in the ABI calling convention.
 ///
 /// # Safety
+///
 /// The caller must ensure to pass parameters appropriate for the usercall `nr`
 /// and to observe all requirements specified in the ABI.
 ///
 /// # Panics
-/// Panics if `nr` is 0.
+///
+/// Panics if `nr` is `0`.
 #[unstable(feature = "sgx_platform", issue = "56975")]
 pub unsafe fn do_usercall(nr: u64, p1: u64, p2: u64, p3: u64, p4: u64) -> (u64, u64) {
     if nr==0 { panic!("Invalid usercall number {}",nr) }
diff --git a/src/libstd/sys/sgx/waitqueue.rs b/src/libstd/sys/sgx/waitqueue.rs
index 51c00a1433e..aec643b3175 100644
--- a/src/libstd/sys/sgx/waitqueue.rs
+++ b/src/libstd/sys/sgx/waitqueue.rs
@@ -3,7 +3,7 @@
 /// This queue is used to implement condition variable and mutexes.
 ///
 /// Users of this API are expected to use the `WaitVariable<T>` type. Since
-/// that type is not `Sync`, it needs to be protected by e.g. a `SpinMutex` to
+/// that type is not `Sync`, it needs to be protected by e.g., a `SpinMutex` to
 /// allow shared access.
 ///
 /// Since userspace may send spurious wake-ups, the wakeup event state is
@@ -136,7 +136,7 @@ impl WaitQueue {
         self.inner.is_empty()
     }
 
-    /// Add the calling thread to the WaitVariable's wait queue, then wait
+    /// Adds the calling thread to the `WaitVariable`'s wait queue, then wait
     /// until a wakeup event.
     ///
     /// This function does not return until this thread has been awoken.