filedescriptor: add some doc comments

filedescriptor/src/lib.rs

@@ -9,56 +9,109 @@ mod windows;
 #[cfg(windows)]
 pub use crate::windows::*;
 
+/// `AsRawFileDescriptor` is a platform independent trait for returning
+/// a non-owning reference to the underlying platform file descriptor
+/// type.
 pub trait AsRawFileDescriptor {
     fn as_raw_file_descriptor(&self) -> RawFileDescriptor;
 }
 
+/// `IntoRawFileDescriptor` is a platform independent trait for converting
+/// an instance into the underlying platform file descriptor type.
 pub trait IntoRawFileDescriptor {
     fn into_raw_file_descriptor(self) -> RawFileDescriptor;
 }
 
+/// `FromRawFileDescriptor` is a platform independent trait for creating
+/// an instance from the underlying platform file descriptor type.
+/// Because the platform file descriptor type has no inherent ownership
+/// management, the `from_raw_file_descrptor` function is marked as unsafe
+/// to indicate that care must be taken by the caller to ensure that it
+/// is used appropriately.
 pub trait FromRawFileDescriptor {
     unsafe fn from_raw_file_descrptor(fd: RawFileDescriptor) -> Self;
 }
 
+/// `OwnedHandle` allows managing the lifetime of the platform `RawFileDescriptor`
+/// type.  It is exposed in the interface of this crate primarily for convenience
+/// on Windows where the system handle type is used for a variety of objects
+/// that don't support reading and writing.
 #[derive(Debug)]
 pub struct OwnedHandle {
     handle: RawFileDescriptor,
 }
 
 impl OwnedHandle {
+    /// Create a new handle from some object that is convertible into
+    /// the system `RawFileDescriptor` type.  This consumes the parameter
+    /// and replaces it with an `OwnedHandle` instance.
     pub fn new<F: IntoRawFileDescriptor>(f: F) -> Self {
         Self {
             handle: f.into_raw_file_descriptor(),
         }
     }
 
+    /// Attempt to duplicate the underlying handle and return an
+    /// `OwnedHandle` wrapped around the duplicate.  Since the duplication
+    /// requires kernel resources that may not be available, this is a
+    /// potentially fallible operation.
+    /// The returned handle has a separate lifetime from the source, but
+    /// references the same object at the kernel level.
     pub fn try_clone(&self) -> Fallible<Self> {
         Self::dup(self)
     }
+
+    /// Attempt to duplicate the underlying handle from an object that is
+    /// representable as the systemm `RawFileDescriptor` type and return an
+    /// `OwnedHandle` wrapped around the duplicate.  Since the duplication
+    /// requires kernel resources that may not be available, this is a
+    /// potentially fallible operation.
+    /// The returned handle has a separate lifetime from the source, but
+    /// references the same object at the kernel level.
+    pub fn dup<F: AsRawFileDescriptor>(f: &F) -> Fallible<Self> {
+        Self::dup_impl(f)
+    }
 }
 
+/// `FileDescriptor` is a thin wrapper on top of the `OwnedHandle` type that
+/// exposes the ability to Read and Write to the platform `RawFileDescriptor`.
 #[derive(Debug)]
 pub struct FileDescriptor {
     handle: OwnedHandle,
 }
 
+impl FileDescriptor {
+    /// Create a new descriptor from some object that is convertible into
+    /// the system `RawFileDescriptor` type.  This consumes the parameter
+    /// and replaces it with a `FileDescriptor` instance.
+    pub fn new<F: IntoRawFileDescriptor>(f: F) -> Self {
+        let handle = OwnedHandle::new(f);
+        Self { handle }
+    }
+
+    /// Attempt to duplicate the underlying handle from an object that is
+    /// representable as the systemm `RawFileDescriptor` type and return a
+    /// `FileDescriptor` wrapped around the duplicate.  Since the duplication
+    /// requires kernel resources that may not be available, this is a
+    /// potentially fallible operation.
+    /// The returned handle has a separate lifetime from the source, but
+    /// references the same object at the kernel level.
+    pub fn dup<F: AsRawFileDescriptor>(f: &F) -> Fallible<Self> {
+        OwnedHandle::dup(f).map(|handle| Self { handle })
+    }
+
+    /// Attempt to duplicate the underlying handle and return a
+    /// `FileDescriptor` wrapped around the duplicate.  Since the duplication
+    /// requires kernel resources that may not be available, this is a
+    /// potentially fallible operation.
+    /// The returned handle has a separate lifetime from the source, but
+    /// references the same object at the kernel level.
+    pub fn try_clone(&self) -> Fallible<Self> {
+        self.handle.try_clone().map(|handle| Self { handle })
+    }
+}
+
 pub struct Pipes {
     pub read: FileDescriptor,
     pub write: FileDescriptor,
 }
-
-impl FileDescriptor {
-    pub fn new<F: IntoRawFileDescriptor>(f: F) -> Self {
-        let handle = OwnedHandle::new(f);
-        Self { handle }
-    }
-
-    pub fn dup<F: AsRawFileDescriptor>(f: &F) -> Fallible<Self> {
-        OwnedHandle::dup(f).map(|handle| Self { handle })
-    }
-
-    pub fn try_clone(&self) -> Fallible<Self> {
-        self.handle.try_clone().map(|handle| Self { handle })
-    }
-}

filedescriptor/src/unix.rs

@@ -5,6 +5,9 @@ use crate::{
 use failure::{bail, Fallible};
 use std::os::unix::prelude::*;
 
+/// `RawFileDescriptor` is a platform independent type alias for the
+/// underlying platform file descriptor type.  It is primarily useful
+/// for avoiding using `cfg` blocks in platform independent code.
 pub type RawFileDescriptor = RawFd;
 
 impl<T: AsRawFd> AsRawFileDescriptor for T {
@@ -73,7 +76,8 @@ impl OwnedHandle {
         Ok(())
     }
 
-    pub fn dup<F: AsRawFileDescriptor>(fd: &F) -> Fallible<Self> {
+    #[inline]
+    pub(crate) fn dup_impl<F: AsRawFileDescriptor>(fd: &F) -> Fallible<Self> {
         let fd = fd.as_raw_file_descriptor();
         let duped = unsafe { libc::dup(fd) };
         if duped == -1 {

filedescriptor/src/windows.rs

@@ -12,6 +12,9 @@ use winapi::um::handleapi::*;
 use winapi::um::namedpipeapi::CreatePipe;
 use winapi::um::processthreadsapi::*;
 
+/// `RawFileDescriptor` is a platform independent type alias for the
+/// underlying platform file descriptor type.  It is primarily useful
+/// for avoiding using `cfg` blocks in platform independent code.
 pub type RawFileDescriptor = RawHandle;
 
 impl<T: AsRawHandle> AsRawFileDescriptor for T {
@@ -49,7 +52,8 @@ impl FromRawHandle for OwnedHandle {
 }
 
 impl OwnedHandle {
-    pub fn dup<F: AsRawFileDescriptor>(f: &F) -> Fallible<Self> {
+    #[inline]
+    pub(crate) fn dup_impl<F: AsRawFileDescriptor>(f: &F) -> Fallible<Self> {
         let handle = f.as_raw_file_descriptor();
         if handle == INVALID_HANDLE_VALUE || handle.is_null() {
             return Ok(OwnedHandle { handle });