From: Derrick Stolee <stolee@gmail.com>
Date: Tue, 24 Aug 2021 17:01:38 GMT
Subject: Re: [PATCH v2 1/4] bundle API: start writing API documentation
Message-ID: <1193fbe3-f4f6-d8e7-3730-770d2932655d@gmail.com>
In-Reply-To: <patch-v2-1.4-dc8591f6d0b-20210823T110136Z-avarab@gmail.com>

On 8/23/2021 7:02 AM, Ævar Arnfjörð Bjarmason wrote:
> There are no other API docs in bundle.h, but this is at least a
> start. We'll add a parameter to this function in a subsequent commit,
> but let's start by documenting it.
> 
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
>  bundle.h | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/bundle.h b/bundle.h
> index 1927d8cd6a4..84a6df1b65d 100644
> --- a/bundle.h
> +++ b/bundle.h
> @@ -27,6 +27,13 @@ int create_bundle(struct repository *r, const char *path,
>  		  int version);
>  int verify_bundle(struct repository *r, struct bundle_header *header, int verbose);
>  #define BUNDLE_VERBOSE 1
> +
> +/**

nit: what's the use of the "/**" start to these doc comments?

I see examples in the codebase of both, but we are not consistent even
within a single file. Here is how I counted instances of each:

$ git grep "^/\\*\\*\$" -- *.h | wc -l
266
$ git grep "^/\\*\$" -- *.h | wc -l
775

So we use "/*" three times as often as "/**". Should we attempt to
be more consistent in the future?

Thanks,
-Stolee