Add some documentation comments

21 files changed, 159 insertions, 1 deletions

diff --git a/bfs.h b/bfs.h
index 34fdc3c..d5d3f93 100644
--- a/bfs.h
+++ b/bfs.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * Constants about the bfs program itself.
+ */
+
 #ifndef BFS_H
 #define BFS_H
 
diff --git a/bftw.h b/bftw.h
index eff24bc..bed5800 100644
--- a/bftw.h
+++ b/bftw.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * A file-walking API based on nftw().
+ */
+
 #ifndef BFS_BFTW_H
 #define BFS_BFTW_H
 
diff --git a/cmdline.h b/cmdline.h
index 78e1f9a..4a1ef3b 100644
--- a/cmdline.h
+++ b/cmdline.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * Representation of the parsed command line.
+ */
+
 #ifndef BFS_CMDLINE_H
 #define BFS_CMDLINE_H
 
diff --git a/color.c b/color.c
index 333b547..27df6a0 100644
--- a/color.c
+++ b/color.c
@@ -29,6 +29,9 @@
 #include <sys/stat.h>
 #include <unistd.h>
 
+/**
+ * A color for a file extension.
+ */
 struct ext_color {
 	const char *ext;
 	size_t len;
@@ -38,6 +41,9 @@ struct ext_color {
 	struct ext_color *next;
 };
 
+/**
+ * The parsed form of LS_COLORS.
+ */
 struct colors {
 	const char *reset;
 	const char *bold;
@@ -77,6 +83,9 @@ struct colors {
 	char *data;
 };
 
+/**
+ * A named color for parsing and lookup.
+ */
 struct color_name {
 	const char *name;
 	size_t offset;
@@ -84,6 +93,9 @@ struct color_name {
 
 #define COLOR_NAME(name, field) {name, offsetof(struct colors, field)}
 
+/**
+ * All the known color names that can be referenced in LS_COLORS.
+ */
 static const struct color_name color_names[] = {
 	COLOR_NAME("bd", block),
 	COLOR_NAME("bld", bold),
@@ -118,6 +130,7 @@ static const struct color_name color_names[] = {
 	{0},
 };
 
+/** Get a color from the table. */
 static const char **get_color(const struct colors *colors, const char *name) {
 	for (const struct color_name *entry = color_names; entry->name; ++entry) {
 		if (strcmp(name, entry->name) == 0) {
@@ -128,6 +141,7 @@ static const char **get_color(const struct colors *colors, const char *name) {
 	return NULL;
 }
 
+/** Set the value of a color. */
 static void set_color(struct colors *colors, const char *name, const char *value) {
 	const char **color = get_color(colors, name);
 	if (color) {
@@ -288,6 +302,7 @@ int cfclose(CFILE *cfile) {
 	return ret;
 }
 
+/** Get the color for a file by its extension. */
 static const char *ext_color(const struct colors *colors, const char *filename) {
 	size_t namelen = strlen(filename);
 
@@ -305,6 +320,7 @@ static const char *ext_color(const struct colors *colors, const char *filename)
 	return NULL;
 }
 
+/** Get the color for a file. */
 static const char *file_color(const struct colors *colors, const char *filename, const struct BFTW *ftwbuf) {
 	const struct bfs_stat *sb = ftwbuf->statbuf;
 	if (!sb) {
@@ -394,6 +410,7 @@ static const char *file_color(const struct colors *colors, const char *filename,
 	return color;
 }
 
+/** Print an ANSI escape sequence. */
 static int print_esc(const char *esc, FILE *file) {
 	if (fputs("\033[", file) == EOF) {
 		return -1;
@@ -408,6 +425,7 @@ static int print_esc(const char *esc, FILE *file) {
 	return 0;
 }
 
+/** Print a string with an optional color. */
 static int print_colored(const struct colors *colors, const char *esc, const char *str, size_t len, FILE *file) {
 	if (esc) {
 		if (print_esc(esc, file) != 0) {
@@ -426,6 +444,7 @@ static int print_colored(const struct colors *colors, const char *esc, const cha
 	return 0;
 }
 
+/** Print the path to a file with the appropriate colors. */
 static int print_path(CFILE *cfile, const struct BFTW *ftwbuf) {
 	const struct colors *colors = cfile->colors;
 	FILE *file = cfile->file;
@@ -450,6 +469,7 @@ static int print_path(CFILE *cfile, const struct BFTW *ftwbuf) {
 	return 0;
 }
 
+/** Print a link target with the appropriate colors. */
 static int print_link(CFILE *cfile, const struct BFTW *ftwbuf) {
 	int ret = -1;
 
diff --git a/color.h b/color.h
index 78db64a..7df3785 100644
--- a/color.h
+++ b/color.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * Utilities for colored output on ANSI terminals.
+ */
+
 #ifndef BFS_COLOR_H
 #define BFS_COLOR_H
 
diff --git a/diag.h b/diag.h
index e84bbc1..54f2366 100644
--- a/diag.h
+++ b/diag.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * Formatters for diagnostic messages.
+ */
+
 #ifndef BFS_DIAG_H
 #define BFS_DIAG_H
 
diff --git a/dstring.c b/dstring.c
index f4a865a..10e1557 100644
--- a/dstring.c
+++ b/dstring.c
@@ -27,10 +27,12 @@ struct dstring {
 	char data[];
 };
 
+/** Get the string header from the string data pointer. */
 static struct dstring *dstrheader(const char *dstr) {
 	return (struct dstring *)(dstr - offsetof(struct dstring, data));
 }
 
+/** Get the correct size for a dstring with the given capacity. */
 static size_t dstrsize(size_t capacity) {
 	return sizeof(struct dstring) + capacity + 1;
 }
@@ -81,6 +83,7 @@ int dstresize(char **dstr, size_t length) {
 	return 0;
 }
 
+/** Common implementation of dstr{cat,ncat,app}. */
 static int dstrcat_impl(char **dest, const char *src, size_t srclen) {
 	size_t oldlen = dstrlen(*dest);
 	size_t newlen = oldlen + srclen;
diff --git a/dstring.h b/dstring.h
index 1beccb5..d43a1f0 100644
--- a/dstring.h
+++ b/dstring.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * A dynamic string library.
+ */
+
 #ifndef BFS_DSTRING_H
 #define BFS_DSTRING_H
 
diff --git a/eval.c b/eval.c
index e05aff1..b41ebf6 100644
--- a/eval.c
+++ b/eval.c
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * Implementation of all the literal expressions.
+ */
+
 #include "eval.h"
 #include "bftw.h"
 #include "cmdline.h"
diff --git a/eval.h b/eval.h
index 89bf421..91cc944 100644
--- a/eval.h
+++ b/eval.h
@@ -14,6 +14,11 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * The evaluation functions that implement literal expressions like -name,
+ * -print, etc.
+ */
+
 #ifndef BFS_EVAL_H
 #define BFS_EVAL_H
 
diff --git a/exec.h b/exec.h
index 1a75064..78cdbd2 100644
--- a/exec.h
+++ b/exec.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * Implementation of -exec/-execdir/-ok/-okdir.
+ */
+
 #ifndef BFS_EXEC_H
 #define BFS_EXEC_H
 
diff --git a/expr.h b/expr.h
index b7c5c15..0251d6b 100644
--- a/expr.h
+++ b/expr.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * The expression tree representation.
+ */
+
 #ifndef BFS_EXPR_H
 #define BFS_EXPR_H
 
diff --git a/main.c b/main.c
index 066061d..261711b 100644
--- a/main.c
+++ b/main.c
@@ -14,6 +14,37 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * - main(): the entry point for bfs(1), a breadth-first version of find(1)
+ *     - main.c        (this file)
+ *
+ * - parse_cmdline(): parses the command line into an expression tree
+ *     - cmdline.h     (declares the parsed command line structure)
+ *     - expr.h        (declares the expression tree nodes)
+ *     - parse.c       (the parser itself)
+ *     - opt.c         (the expression optimizer)
+ *
+ * - eval_cmdline(): runs the expression on every file it sees
+ *     - eval.[ch]     (the main evaluation functions)
+ *     - exec.[ch]     (implements -exec[dir]/-ok[dir])
+ *     - printf.[ch]   (implements -[f]printf)
+ *
+ * - bftw(): used by eval_cmdline() to walk the directory tree(s)
+ *     - bftw.[ch]     (an extended version of nftw(3))
+ *
+ * - Utilities:
+ *     - bfs.h         (constants about bfs itself)
+ *     - color.[ch]    (for pretty terminal colors)
+ *     - diag.[ch]     (formats diagnostic messages)
+ *     - dstring.[ch]  (a dynamic string library)
+ *     - mtab.[ch]     (parses the system's mount table)
+ *     - posix1e.[ch]  (wraps POSIX.1e functionality, if present)
+ *     - spawn.[ch]    (spawns processes)
+ *     - stat.[ch]     (wraps stat(), or statx() on Linux)
+ *     - typo.[ch]     (fuzzy matching for typos)
+ *     - util.[ch]     (everything else)
+ */
+
 #include "cmdline.h"
 #include "util.h"
 #include <errno.h>
diff --git a/mtab.h b/mtab.h
index e8a021c..ef22716 100644
--- a/mtab.h
+++ b/mtab.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * A facade over platform-specific APIs for enumerating mounted filesystems.
+ */
+
 #ifndef BFS_MTAB_H
 #define BFS_MTAB_H
 
diff --git a/opt.c b/opt.c
index 1157754..dd98ca0 100644
--- a/opt.c
+++ b/opt.c
@@ -14,6 +14,31 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * The expression optimizer.  Different optimization levels are supported:
+ *
+ * -O1: basic logical simplifications, like folding (-true -and -foo) to -foo.
+ *
+ * -O2: dead code elimination and data flow analysis.  struct opt_facts is used
+ * to record data flow facts that are true at various points of evaluation.
+ * Specifically, struct opt_facts records the facts that must be true before an
+ * expression is evaluated (state->facts), and those that must be true after the
+ * expression is evaluated, given that it returns true (state->facts_when_true)
+ * or false (state->facts_when_true).  Additionally, state->facts_when_impure
+ * records the possible data flow facts before any expressions with side effects
+ * are evaluated.
+ *
+ * -O3: expression re-ordering to reduce expected cost.  In an expression like
+ * (-foo -and -bar), if both -foo and -bar are pure (no side effects), they can
+ * be re-ordered to (-bar -and -foo).  This is profitable if the expected cost
+ * is lower for the re-ordered expression, for example if -foo is very slow or
+ * -bar is likely to return false.
+ *
+ * -O4/-Ofast: aggressive optimizations that may affect correctness in corner
+ * cases.  The main effect is to use facts_when_impure to determine if any side-
+ * effects are reachable at all, and skipping the traversal if not.
+ */
+
 #include "cmdline.h"
 #include "color.h"
 #include "eval.h"
diff --git a/parse.c b/parse.c
index 42a5a8f..80aeb88 100644
--- a/parse.c
+++ b/parse.c
@@ -14,6 +14,13 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * The command line parser.  Expressions are parsed by recursive descent, with a
+ * grammar described in the comments of the parse_*() functions.  The parser
+ * also accepts flags and paths at any point in the expression, by treating
+ * flags like always-true options, and skipping over paths wherever they appear.
+ */
+
 #include "bfs.h"
 #include "cmdline.h"
 #include "diag.h"
diff --git a/posix1e.h b/posix1e.h
index 8950498..d3d74ff 100644
--- a/posix1e.h
+++ b/posix1e.h
@@ -14,6 +14,13 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * The withdrawn POSIX.1e standard specified a security API for POSIX systems.
+ * Although it was never ratified, many of its interfaces are widely deployed
+ * in Unix-like systems.  These functions wrap the POSIX.1e APIs if present,
+ * to support things like Access Control Lists and Capabilities.
+ */
+
 #ifndef BFS_POSIX1E_H
 #define BFS_POSIX1E_H
 
diff --git a/printf.h b/printf.h
index 27336eb..1c3957e 100644
--- a/printf.h
+++ b/printf.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * Implementation of -printf/-fprintf.
+ */
+
 #ifndef BFS_PRINTF_H
 #define BFS_PRINTF_H
 
diff --git a/spawn.h b/spawn.h
index ef510e1..a634d6e 100644
--- a/spawn.h
+++ b/spawn.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * A process-spawning library inspired by posix_spawn().
+ */
+
 #ifndef BFS_SPAWN_H
 #define BFS_SPAWN_H
 
diff --git a/stat.h b/stat.h
index d9c9588..3887db4 100644
--- a/stat.h
+++ b/stat.h
@@ -1,6 +1,6 @@
 /****************************************************************************
  * bfs                                                                      *
- * Copyright (C) 2018 Tavian Barnes <tavianator@tavianator.com>             *
+ * Copyright (C) 2018-2019 Tavian Barnes <tavianator@tavianator.com>        *
  *                                                                          *
  * Permission to use, copy, modify, and/or distribute this software for any *
  * purpose with or without fee is hereby granted.                           *
@@ -14,6 +14,14 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * A facade over the stat() API that unifies some details that diverge between
+ * implementations, like the names of the timespec fields and the presence of
+ * file "birth" times.  On new enough Linux kernels, the facade is backed by
+ * statx() instead, and so it exposes a similar interface with a mask for which
+ * fields were successfully returned.
+ */
+
 #ifndef BFS_STAT_H
 #define BFS_STAT_H
 
diff --git a/util.h b/util.h
index 4f70c1b..0a4779f 100644
--- a/util.h
+++ b/util.h
@@ -14,6 +14,10 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  ****************************************************************************/
 
+/**
+ * Assorted utilities that don't belong anywhere else.
+ */
+
 #ifndef BFS_UTIL_H
 #define BFS_UTIL_H