ptyd: add documentation for the `pty' scheme's resources

ptyd/src/controlterm.rs

@@ -1,3 +1,4 @@
+//! Control/manager side of a pseudoterminal (PTY).
 use std::cell::RefCell;
 use std::rc::{Rc, Weak};
 

ptyd/src/pgrp.rs

@@ -1,3 +1,5 @@
+//! "pgrp" resource for the `pty' scheme.
+//! Allows the process group (pgrp) to be changed.
 use std::cell::RefCell;
 use std::rc::Weak;
 

ptyd/src/ptflow.rs

@@ -1,3 +1,5 @@
+//! "flow" resource for the `pty' scheme.
+//! Allows PTY flow control -- stop or restart PTY output.
 use core::ops::DerefMut;
 use std::cell::RefCell;
 use std::rc::Weak;

ptyd/src/ptflush.rs

@@ -1,3 +1,5 @@
+//! "flush" resource for the `pty' scheme.
+//! Clear the pending output for the input, output, or both.
 use std::cell::RefCell;
 use std::rc::Weak;
 

ptyd/src/ptlock.rs

@@ -1,3 +1,7 @@
+//! "ptlock" resource for the `pty' scheme.
+//! Lock and unlock the PTY.
+//! All the lock does currently is prevent terminals from being opened without first being
+//! unlocked.
 use std::cell::RefCell;
 use std::rc::Weak;
 
@@ -36,7 +40,7 @@ impl Resource for PtyLock {
         }
     }
 
-    // FIXME assuming c_int has same size as u32
+    // FIXME: assuming c_int (input) has same size as u32 (output)
     fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
         if let Some(pty_lock) = self.pty.upgrade() {
             let pty = pty_lock.borrow();

ptyd/src/ptname.rs

@@ -1,3 +1,5 @@
+//! "ptsname" resource for the `pty' scheme.
+//! Returns the id of the pseudoterminal subsidiary (PTS) as a u32.
 use std::cell::RefCell;
 use std::rc::Weak;
 

ptyd/src/ptsendbreak.rs

@@ -1,3 +1,5 @@
+//! "sendbreak" resource for the `pty' scheme.
+//! For a PTY, this simply means to sleep for a short amount of time.
 use std::cell::RefCell;
 use std::rc::Weak;
 
@@ -19,8 +21,9 @@ impl PtSendbreak {
         PtSendbreak { pty, flags }
     }
 
+    // The actual hardware break doesn't get sent here because
+    // that is a tty feature, not a pty feature.
     fn sendbreak(&mut self, _duration: c_int) -> Result<usize> {
-        // TODO: send break here
         let _ = unsafe {
             // POSIX specifies that we need to sleep for 0.25 to 0.5 seconds.
             // FreeBSD uses 0.4, and that seems reasonable.
@@ -30,8 +33,6 @@ impl PtSendbreak {
             };
             nanosleep(&tm, core::ptr::null_mut())
         };
-        // TODO: end break here
-
         Ok(4)
     }
 }