From b949b90dd7f7a24014018f7617d5f30c80775fa3 Mon Sep 17 00:00:00 2001
From: Danny Robson <danny@nerdcruft.net>
Date: Sun, 2 Oct 2016 16:34:40 +1100
Subject: [PATCH] posix/fd: add more comments

---
 posix/fd.cpp |  9 +++------
 posix/fd.hpp | 11 +++++++++++
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/posix/fd.cpp b/posix/fd.cpp
index c71a0ce0..7d437d22 100644
--- a/posix/fd.cpp
+++ b/posix/fd.cpp
@@ -43,7 +43,7 @@ fd::fd (const char *path, int flags, mode_t mode):
 }
 
 
-//-----------------------------------------------------------------------------
+///////////////////////////////////////////////////////////////////////////////
 fd::fd (fd &&rhs):
     m_fd (-1)
 {
@@ -51,13 +51,10 @@ fd::fd (fd &&rhs):
 }
 
 
-//-----------------------------------------------------------------------------
+///////////////////////////////////////////////////////////////////////////////
 fd::fd (int _fd):
     m_fd (_fd)
-{
-    if (_fd < 0)
-        throw std::invalid_argument ("invalid descriptor");
-}
+{ ; }
 
 
 ///////////////////////////////////////////////////////////////////////////////
diff --git a/posix/fd.hpp b/posix/fd.hpp
index a9c05332..a35b72cc 100644
--- a/posix/fd.hpp
+++ b/posix/fd.hpp
@@ -25,20 +25,31 @@ namespace util::posix {
     /// A simple RAII wrapper for file descriptors
     class fd {
     public:
+        ///////////////////////////////////////////////////////////////////////
         fd (const char *path, int flags);
         fd (const char *path, int flags, mode_t);
 
         fd (fd &&);
+
+        // The int constructor steals the fd. So don't pass in something that
+        // you don't want closed at destruct time. This should really only be
+        // used when interfacing with results of syscalls that we don't wrap.
         explicit fd (int);
 
+        // copy constructors are removed in favour of explicit calls to dup.
+        // This should reduce unexpected or expensive copies as much as
+        // possible; one should not be doing this unless it is absolutely
+        // required.
         fd (const fd&) = delete;
         fd dup (void) const;
         static fd dup (int);
 
         ~fd ();
 
+        ///////////////////////////////////////////////////////////////////////
         struct ::stat stat (void) const;
 
+        ///////////////////////////////////////////////////////////////////////
         operator int (void) const;
 
     private: