dir_action comments and docs

src/fs/dir_action.rs

@@ -1,4 +1,24 @@
-/// What to do when encountering a directory?
+//! What to do when encountering a directory?
+
+/// The action to take when trying to list a file that turns out to be a
+/// directory.
+///
+/// By default, exa will display the information about files passed in as
+/// command-line arguments, with one file per entry. However, if a directory
+/// is passed in, exa assumes that the user wants to see its contents, rather
+/// than the directory itself.
+///
+/// This can get annoying sometimes: if a user does `exa ~/Downloads/img-*`
+/// to see the details of every file starting with `img-`, any directories
+/// that happen to start with the same will be listed after the files at
+/// the end in a separate block. By listing directories as files, their
+/// directory status will be ignored, and both will be listed side-by-side.
+///
+/// These two modes have recursive analogues in the “recurse” and “tree”
+/// modes. Here, instead of just listing the directories, exa will descend
+/// into them and print out their contents. The recurse mode does this by
+/// having extra output blocks at the end, while the tree mode will show
+/// directories inline, with their contents immediately underneath.
 #[derive(PartialEq, Debug, Copy, Clone)]
 pub enum DirAction {
 
@@ -21,7 +41,7 @@ impl DirAction {
     /// Gets the recurse options, if this dir action has any.
     pub fn recurse_options(&self) -> Option<RecurseOptions> {
         match *self {
-            DirAction::Recurse(opts) => Some(opts),
+            DirAction::Recurse(o) => Some(o),
             _                     => None,
         }
     }
@@ -30,7 +50,7 @@ impl DirAction {
     pub fn treat_dirs_as_files(&self) -> bool {
         match *self {
             DirAction::AsFile      => true,
-            DirAction::Recurse(RecurseOptions { tree, .. }) => tree,
+            DirAction::Recurse(o)  => o.tree,
             _                      => false,
         }
     }
@@ -56,9 +76,7 @@ impl RecurseOptions {
     pub fn is_too_deep(&self, depth: usize) -> bool {
         match self.max_depth {
             None    => false,
-            Some(d) => {
-                d <= depth
-            }
+            Some(d) => d <= depth
         }
     }
 }

src/options/dir_action.rs

@@ -1,3 +1,5 @@
+//! Parsing the options for `DirAction`.
+
 use options::parser::MatchedFlags;
 use options::{flags, Misfire};
 
@@ -7,6 +9,9 @@ use fs::dir_action::{DirAction, RecurseOptions};
 impl DirAction {
 
     /// Determine which action to perform when trying to list a directory.
+    /// There are three possible actions, and they overlap somewhat: the
+    /// `--tree` flag is another form of recursion, so those two are allowed
+    /// to both be present, but the `--list-dirs` flag is used separately.
     pub fn deduce(matches: &MatchedFlags) -> Result<DirAction, Misfire> {
         let recurse = matches.has(&flags::RECURSE)?;
         let as_file = matches.has(&flags::LIST_DIRS)?;
@@ -43,7 +48,10 @@ impl DirAction {
 
 impl RecurseOptions {
 
-    /// Determine which files should be recursed into.
+    /// Determine which files should be recursed into, based on the `--level`
+    /// flag’s value, and whether the `--tree` flag was passed, which was
+    /// determined earlier. The maximum level should be a number, and this
+    /// will fail with an `Err` if it isn’t.
     pub fn deduce(matches: &MatchedFlags, tree: bool) -> Result<RecurseOptions, Misfire> {
         let max_depth = if let Some(level) = matches.get(&flags::LEVEL)? {
             match level.to_string_lossy().parse() {