Re: [PATCH 8/8] replace and remove run_command_v_opt()

["René Scharfe" <l.s.r@web.de>]

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@web.de>
---
 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