Write implementation overview.

diff --git a/src/rm.c b/src/rm.c
index a304df9834385aa41fb1824bd162b1f3c1a89ae0..fcb678f3959052995ff09a030fc84f01f96cd773 100644 (file)
--- a/src/rm.c
+++ b/src/rm.c
@@ -18,6 +18,31 @@
 /* Written by Paul Rubin, David MacKenzie, and Richard Stallman.
    Reworked to use chdir and hash tables by Jim Meyering.  */
 
+/* Implementation overview:
+
+   In the `usual' case RM saves no state for directories it is processing.
+   When a removal fails (either due to an error or to an interactive `no'
+   reply), the failure is noted (see descriptin of `ht' remove_cwd_entries)
+   so that when/if the containing directory is reopened, RM doesn't try to
+   remove the entry again.
+
+   RM may delete arbitrarily deep hierarchies -- even ones in which file
+   names (from root to leaf) are longer than the system-imposed maximum.
+   It does this by using chdir to change to each directory in turn before
+   removing the entries in that directory.
+
+   RM detects directory cycles by maintaining a table of the currently
+   active directories.  See the description of active_dir_map below.
+
+   RM is careful to avoid forming full file names whenever possible.
+   A full file name is formed only when it is about to be used -- e.g.
+   in a diagnostic or in an interactive mode prompt.
+
+   RM minimizes the number of lstat system calls it makes.  On systems
+   that have valid d_type data in directory entries, RM makes only one
+   lstat call per command line argument -- regardless of the depth of
+   the hierarchy.  */
+
 #include <config.h>
 #include <stdio.h>
 #include <getopt.h>