loop_{args,files}: add comment

1 files changed, 11 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));