From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Thu, 10 Mar 2022 14:37:44 GMT
Subject: Re: [PATCH 4/4] trace2 docs: clarify what `varargs` is all about
Message-ID: <220310.86ee39kh0v.gmgdl@evledraar.gmail.com>
In-Reply-To: <2eecea50e5132b09574451f37ca76a5d4af8697f.1646919331.git.gitgitgadget@gmail.com>


On Thu, Mar 10 2022, Johannes Schindelin via GitGitGadget wrote:

> From: Johannes Schindelin <johannes.schindelin@gmx.de>
>
> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
> ---
>  Documentation/technical/api-trace2.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt
> index 285f713ed84..91985512867 100644
> --- a/Documentation/technical/api-trace2.txt
> +++ b/Documentation/technical/api-trace2.txt
> @@ -170,7 +170,7 @@ Some functions have a `_va_fl()` suffix to indicate that they also
>  take a `va_list` argument.
>  
>  Some functions have a `_printf_fl()` suffix to indicate that they also
> -take a varargs argument.
> +take a `printf()` style format with a variable number of arguments.

This is correct, but I think better would be to explicitly describe the
_printf_va_fl() suffix in this list, i.e. now that implicitly falls
under _va_fl(), so it's *technically* redundant.

But either describing it explicitly, or saying that `_printf_*_fl()` are
function that take a printf format before either a "va_args" or "..."
would make the end-state a bit more obvious.

I wonder if the pre-image wanted to describe `_printf_va_fl()` (which
would make it correct), and we just omitted a `printf_fl()` description.