Am 28.10.22 um 00:41 schrieb Ævar Arnfjörð Bjarmason:
>
> On Thu, Oct 27 2022, René Scharfe wrote:
>
>> #ifndef NO_PTHREADS
>> static pthread_t main_thread;
>> static int main_thread_set;
>> diff --git a/run-command.h b/run-command.h
>> index 04bd07dc7a..fe2717ad11 100644
>> --- a/run-command.h
>> +++ b/run-command.h
>> @@ -151,7 +151,7 @@ struct child_process {
>>
>> /**
>> * The functions: child_process_init, start_command, finish_command,
>> - * run_command, run_command_v_opt, child_process_clear do the following:
>> + * run_command, child_process_clear do the following:
>> *
>> * - If a system call failed, errno is set and -1 is returned. A diagnostic
>> * is printed.
>
> A pre-existing issue mostly, but maybe worth cleaning up while we're
> fixing these docs in general.
>
> This summary is incorrect, because the first bullet point is claiming
> that these "return -1", but 2 functions on this list return void.
>
> It looks to me if we just remove child_process_{init,clear} altgother
> from this it'll be correct. They have their own docs below, and this is
> really describing how this now-simpler API works vis-a-vis the
> start/run/finish functions.
True, and I added that mistake a while ago. Oops.
--- >8 ---
Subject: [PATCH 9/8] run-command: fix return value comment
483bbd4e4c (run-command: introduce child_process_init(), 2014-08-19) and
2d71608ec0 (run-command: factor out child_process_clear(), 2015-10-24)
added help texts about child_process_init() and child_process_clear()
without updating the immediately following documentation of return codes
that only applied to the preexisting functions.
4c4066d95d (run-command: move doc to run-command.h, 2019-11-17) started
to list the functions explicitly that this paragraph applies to, but
still wrongly included child_process_init() and child_process_clear().
Remove their names from that list.
Signed-off-by: René Scharfe <l.s.r@xxxxxx>
---
run-command.h | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/run-command.h b/run-command.h
index fe2717ad11..7ed2c04427 100644
--- a/run-command.h
+++ b/run-command.h
@@ -150,8 +150,7 @@ struct child_process {
}
/**
- * The functions: child_process_init, start_command, finish_command,
- * run_command, child_process_clear do the following:
+ * The functions start_command, finish_command, run_command do the following:
*
* - If a system call failed, errno is set and -1 is returned. A diagnostic
* is printed.
--
2.38.1
