Better documentation to conform to standards

Author: ctrlcctrlv

src/unistd.rs

@@ -2344,6 +2344,12 @@ mod setres {
 
 
 #[derive(Debug, Clone, PartialEq, Default)]
+/// Representation of a user, based on `libc::passwd`
+///
+/// The reason some fields in this struct are `String` and others are `CString` is because some
+/// fields are based on the user's locale, which could be non-UTF8, while other fields are
+/// guaranteed to conform to [NAME_REGEX](https://serverfault.com/a/73101/407341), which only
+/// contains ASCII.
 pub struct User {
     /// username
     pub name: String,
@@ -2394,13 +2400,14 @@ impl From<libc::passwd> for User {
     }
 }
 
+/// Representation of a group, based on `libc::group`
 #[derive(Debug, Clone, PartialEq)]
 pub struct Group {
     /// group name
     pub name: String,
     /// group ID
     pub gid: Gid,
-    /// list of members
+    /// list of group members
     pub mem: Vec<String>
 }
 
@@ -2435,29 +2442,62 @@ impl Group {
 }
 
 #[derive(Debug)]
-/// Query a group. The buffer size variants should not be needed 99% of the time; the default
-/// buffer size of 1024 should be more than adequate. Only use the buffer size variants if you
-/// receive an ERANGE error without them, or you know that you will be likely to.
+/// Query a user.
+///
+/// The buffer size variants should not be needed 99% of the time; the default buffer size of 1024
+/// should be more than adequate. Only use the buffer size variants if you receive an ERANGE error
+/// without them, or you know that you will be likely to.
+///
+/// # Example
+///
+/// ```
+/// let find = String::from("root");
+/// // Returns an Option<Result<User>>, thus the double unwrap.
+/// let res = User::query( UserQuery::Name(find) ).unwrap().unwrap();
+/// assert!(res.name == find);
+/// ```
 pub enum UserQuery {
-    /// Get a user by UID. Internally, this function calls
+    /// Get a user by UID. 
+    ///
+    /// Internally, this function calls
     /// [getpwuid_r(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getpwuid_r.html)
     Uid(Uid),
-    /// Get a user by name. Internally, this function calls
+    /// Get a user by name. 
+    ///
+    /// Internally, this function calls
     /// [getpwnam_r(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getpwuid_r.html)
     Name(String),
     UidWithBufsize(Uid, usize),
     NameWithBufsize(String, usize)
 }
 
+/// Query a group. 
+///
+/// The buffer size variants should not be needed 99% of the time; the default buffer size of 1024
+/// should be more than adequate. Only use the buffer size variants if you receive an ERANGE error
+/// without them, or you know that you will be likely to.
+///
+/// # Example
+///
+/// ```ignore
+/// use nix::unistd::{Group, GroupQuery};
+/// // On many systems there's no `root` group; on FreeBSD for example it's known as `wheel`
+/// let find = String::from("root");
+/// // Returns an Option<Result<Group>>, thus the double unwrap. Will panic if there's no `root`
+/// // group.
+/// let res = Group::query( GroupQuery::Name(find) ).unwrap().unwrap();
+/// assert!(res.name == find);
+/// ```
 #[derive(Debug)]
-/// Query a user. The buffer size variants should not be needed 99% of the time; the default buffer
-/// size of 1024 should be more than adequate. Only use the buffer size variants if you receive an
-/// ERANGE error without them, or you know that you will be likely to.
 pub enum GroupQuery {
-    /// Get a group by GID. Internally, this function calls
+    /// Get a group by GID. 
+    ///
+    /// Internally, this function calls
     /// [getgrgid_r(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getpwuid_r.html)
     Gid(Gid),
-    /// Get a group by name. Internally, this function calls
+    /// Get a group by name. 
+    ///
+    /// Internally, this function calls
     /// [getgrnam_r(3)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/getpwuid_r.html)
     Name(String),
     GidWithBufsize(Gid, usize),
@@ -2582,7 +2622,9 @@ mod usergroupiter {
     use super::{Error, User, Group, PWGRP_BUFSIZE};
     use std::{mem, ptr};
 
-    /// This iterator can be used to get all of the users on the system. For example:
+    /// Used to get all of the users on the system.
+    ///
+    /// # Example
     ///
     /// ```
     /// use nix::unistd::Users;
@@ -2596,6 +2638,8 @@ mod usergroupiter {
     /// 
     /// ```
     ///
+    /// # Safety
+    ///
     /// This iterator should not be used in different threads without synchronization; while doing so
     /// will not cause undefined behavior, because modern systems lack re-entrant versions of
     /// `setpwent` and `endpwent`, it is very likely that iterators running in different threads will
@@ -2644,7 +2688,9 @@ mod usergroupiter {
         }
     }
 
-    /// This iterator can be used to get all of the groups on the system. For example:
+    /// Used to get all of the groups on the system.
+    ///
+    /// # Example
     ///
     /// ```
     /// use nix::unistd::Groups;
@@ -2655,9 +2701,10 @@ mod usergroupiter {
     ///                        gr.name,
     ///                        gr.gid)))
     ///      .collect::<Vec<_>>();
-    /// 
     /// ```
     ///
+    /// # Safety
+    ///
     /// This iterator should not be used in different threads without synchronization; while doing so
     /// will not cause undefined behavior, because modern systems lack re-entrant versions of
     /// `setgrent` and `endgrent`, it is very likely that iterators running in different threads will