[PATCH 05/10] run-command API docs: clarify & fleshen out run_command_v_opt*() docs
- From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- Date
- Oct 14, 2022, 15:40 UTC
- Message-ID
- <patch-05.10-b6a3c4c66f8-20221014T153426Z-avarab@gmail.com>
- In-Reply-To
- <cover-00.10-00000000000-20221014T153426Z-avarab@gmail.com>
Add a discussion of the flags that were missing to the run_command_v_opt*() docs, and in doing so format them such that we can easily add or remove flags from a table in the future, rather than having them tied up in prose.
Let's also clarify why the user might want to use this API over run_command() itself.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> --- run-command.h | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-)
diff --git a/run-command.h b/run-command.h index 6320d70f062..cf250e36426 100644 --- a/run-command.h +++ b/run-command.h @@ -234,13 +234,28 @@ int run_auto_maintenance(int quiet); #define RUN_CLOSE_OBJECT_STORE (1<<7) /** - * Convenience functions that encapsulate a sequence of - * start_command() followed by finish_command(). The argument argv - * specifies the program and its arguments. The argument opt is zero - * or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, - * `RUN_COMMAND_STDOUT_TO_STDERR`, or `RUN_SILENT_EXEC_FAILURE` - * that correspond to the members .no_stdin, .git_cmd, - * .stdout_to_stderr, .silent_exec_failure of `struct child_process`. + * The run_command_v_opt*() API is a convenience wrapper for an + * underlying run_command(). + * + * It's intended to be used when the user already has an "argv" they'd + * like to use. As opposed to the "struct child_process"'s "args" + * member, which will be strvec_clear()'d by calling run_command(), + * the caller owns the "argv", which is not altered by invoking these + * functions. + * + * The "opt" flags that will cause various underlying run_command() + * members to be set. The flags and the corresponding struct members + * are: + * + * - RUN_COMMAND_NO_STDIN: .no_stdin + * - RUN_GIT_CMD: .git_cmd + * - RUN_COMMAND_STDOUT_TO_STDERR: .stdout_to_stderr + * - RUN_SILENT_EXEC_FAILURE: .silent_exec_failure + * - RUN_USING_SHELL: .use_shell + * - RUN_CLEAN_ON_EXIT: .clean_on_exit + * - RUN_WAIT_AFTER_CLEAN: .wait_after_clean + * - RUN_CLOSE_OBJECT_STORE: .close_object_store + * * The argument dir corresponds the member .dir. The argument env * corresponds to the member .env. */
-- 2.38.0.1092.g8c0298861b0