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

From: Derrick Stolee <stolee@gmail.com>
Date: Aug 24, 2021, 17:01 UTC
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:

Show 19 quoted lines

> 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