Improve documentation about maintaining LineHandles

README.md

@@ -139,7 +139,9 @@ Using the sysfs API, one would write the global GPIO number to the "export" file
 to perform further operations using new files on the filesystem.  Using the
 gpiochip character device, a handle for performing operations on one or more
 GPIO offsets within a chip are available via a "linehandle" fd created using the
-`GPIO_GET_LINEHANDLE_IOCTL`.
+`GPIO_GET_LINEHANDLE_IOCTL`. A consequence of this is that a line will remember
+its state only for as long as the fd is open; the line's state will be reset
+once the fd is closed.
 
 When a linehandle is requested, additional information is also included about
 how the individual GPIOs will be used (input, output, as-is, active-low, open

examples/driveoutput.rs

@@ -27,7 +27,12 @@ fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
     let mut chip = Chip::new(args.chip)?;
 
     // NOTE: we set the default value to the desired state so
-    // setting it separately is not required
+    // setting it separately is not required. The LineHandle
+    // instance that is returned by request must be owned by a
+    // variable for the duration of the time that the line will
+    // be used. If the instance is not assigned to a variable,
+    // then the LineHandle will be immediately dropped after
+    // request returns and the pin will appear to do nothing.
     let _handle =
         chip.get_line(args.line)?
             .request(LineRequestFlags::OUTPUT, args.value, "driveoutput")?;

src/lib.rs

@@ -69,6 +69,9 @@
 //! # fn main() -> Result<()> {
 //! // Read the state of GPIO4 on a raspberry pi.  /dev/gpiochip0
 //! // maps to the driver for the SoC (builtin) GPIO controller.
+//! // The LineHandle returned by request must be assigned to a
+//! // variable (in this case the variable handle) to ensure that
+//! // the corresponding file descriptor is not closed.
 //! let mut chip = Chip::new("/dev/gpiochip0")?;
 //! let handle = chip
 //!     .get_line(4)?