Subject: [PATCH 2/4] parse-options: name flags passed to usage_with_options_internal

From: "D. Ben Knoble" <[email-masked]>
Date: Sat, 26 Jul 2025 12:53:12 -0400

When reading or editing calls to usage_with_options_internal, it is
difficult to tell what trailing "0, 0", "0, 1", "1, 0" arguments mean
(NB there is never a "1, 1" case).

Give the flags readable names to improve call-sites.

Signed-off-by: D. Ben Knoble <[email-masked]>
---
 parse-options.c | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/parse-options.c b/parse-options.c
index 5224203ffe..c3222cc9bb 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -953,10 +953,21 @@ static void free_preprocessed_options(struct option *options)
 	free(options);
 }
 
+enum usage_style {
+	style_normal = 0,
+	style_full = 1,
+};
+
+enum usage_output {
+	to_out = 0,
+	to_err = 1,
+};
+
 static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t *,
 							 const char * const *,
 							 const struct option *,
-							 int, int);
+							 enum usage_style,
+							 enum usage_output);
 
 enum parse_opt_result parse_options_step(struct parse_opt_ctx_t *ctx,
 					 const struct option *options,
@@ -1088,7 +1099,7 @@ enum parse_opt_result parse_options_step(struct parse_opt_ctx_t *ctx,
 		}
 
 		if (internal_help && !strcmp(arg + 2, "help-all"))
-			return usage_with_options_internal(ctx, usagestr, options, 1, 0);
+			return usage_with_options_internal(ctx, usagestr, options, style_full, to_out);
 		if (internal_help && !strcmp(arg + 2, "help"))
 			goto show_usage;
 		switch (parse_long_opt(ctx, arg + 2, options)) {
@@ -1129,7 +1140,7 @@ enum parse_opt_result parse_options_step(struct parse_opt_ctx_t *ctx,
 	return PARSE_OPT_DONE;
 
  show_usage:
-	return usage_with_options_internal(ctx, usagestr, options, 0, 0);
+	return usage_with_options_internal(ctx, usagestr, options, style_normal, to_out);
 }
 
 int parse_options_end(struct parse_opt_ctx_t *ctx)
@@ -1278,10 +1289,11 @@ static const struct option *find_option_by_long_name(const struct option *opts,
 static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t *ctx,
 							 const char * const *usagestr,
 							 const struct option *opts,
-							 int full, int err)
+							 enum usage_style help_style,
+							 enum usage_output to_where)
 {
 	const struct option *all_opts = opts;
-	FILE *outfile = err ? stderr : stdout;
+	FILE *outfile = to_where == to_err ? stderr : stdout;
 	int need_newline;
 
 	const char *usage_prefix = _("usage: %s");
@@ -1327,7 +1339,7 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t
 	if (!usagestr)
 		return PARSE_OPT_HELP;
 
-	if (!err && ctx && ctx->flags & PARSE_OPT_SHELL_EVAL)
+	if (to_where != to_err && ctx && ctx->flags & PARSE_OPT_SHELL_EVAL)
 		fprintf(outfile, "cat <<\\EOF\n");
 
 	while (*usagestr) {
@@ -1373,7 +1385,7 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t
 				fprintf(outfile, "%s\n", _(opts->help));
 			continue;
 		}
-		if (!full && (opts->flags & PARSE_OPT_HIDDEN))
+		if (help_style != style_full && (opts->flags & PARSE_OPT_HIDDEN))
 			continue;
 
 		if (need_newline) {
@@ -1435,7 +1447,7 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t
 	}
 	fputc('\n', outfile);
 
-	if (!err && ctx && ctx->flags & PARSE_OPT_SHELL_EVAL)
+	if (to_where != to_err && ctx && ctx->flags & PARSE_OPT_SHELL_EVAL)
 		fputs("EOF\n", outfile);
 
 	return PARSE_OPT_HELP;
@@ -1444,7 +1456,7 @@ static enum parse_opt_result usage_with_options_internal(struct parse_opt_ctx_t
 void NORETURN usage_with_options(const char * const *usagestr,
 			const struct option *opts)
 {
-	usage_with_options_internal(NULL, usagestr, opts, 0, 1);
+	usage_with_options_internal(NULL, usagestr, opts, style_normal, to_err);
 	exit(129);
 }
 
@@ -1453,7 +1465,7 @@ void show_usage_with_options_if_asked(int ac, const char **av,
 				      const struct option *opts)
 {
 	if (ac == 2 && !strcmp(av[1], "-h")) {
-		usage_with_options_internal(NULL, usagestr, opts, 0, 0);
+		usage_with_options_internal(NULL, usagestr, opts, style_normal, to_out);
 		exit(129);
 	}
 }
-- 
2.48.1