loop_{args,files}: add comment

2 files changed, 25 insertions, 0 deletions

diff --git a/src/util/loop_args.h b/src/util/loop_args.h
index 359ed75..839d104 100644
--- a/src/util/loop_args.h
+++ b/src/util/loop_args.h
@@ -2,4 +2,15 @@
 
 #include <stdbool.h>
 
+/// Call `callback` for every argument provided by `args`.
+/// The arguments are interpreted as filenames, "-" is interpreted as stdin.
+/// If the list of arguments is empty, `callback` is called once with
+/// (NULL, true).
+///
+/// `callback` is expected to return the exit code for the program.
+/// If the exit code is positive, the program will exit immediately with the
+/// provided exit code.
+/// If the exit code is negative enumeration is continued, but after enumeration
+/// the function will return the exit code negated (i.e. the function will
+/// never return a negative integer).
 int loop_args(char **args, int (*callback)(char *arg, bool isstdin));
diff --git a/src/util/loop_files.h b/src/util/loop_files.h
index b436631..8add11d 100644
--- a/src/util/loop_files.h
+++ b/src/util/loop_files.h
@@ -4,4 +4,18 @@
 
 #include "io/read_file.h"
 
+/// Call `callback` for every argument provided by `args`.
+/// The arguments are interpreted as filenames, "-" is interpreted as stdin.
+/// For every argument the given filename is read into a `struct filebuf*`,
+/// which the callee should free (using `free_filebuf`).
+///
+/// If the list of arguments is empty, `callback` is called once with stdin read
+/// into a `filebuf*` and `fname = NULL`.
+///
+/// `callback` is expected to return the exit code for the program.
+/// If the exit code is positive, the program will exit immediately with the
+/// provided exit code.
+/// If the exit code is negative enumeration is continued, but after enumeration
+/// the function will return the exit code negated (i.e. the function will
+/// never return a negative integer).
 int loop_files(char **args, int (*callback)(struct filebuf*, char *fname, bool isstdin));