posix/fd: add more comments

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");
-}
 
 
 ///////////////////////////////////////////////////////////////////////////////

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: