Re: [PATCH v2 1/4] bundle API: start writing API documentation

[Derrick Stolee <stolee@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