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

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Tue, Aug 24 2021, Derrick Stolee wrote:

> 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?

They're not the same thing. "/*\n" is a normal comment, "/**\n" is an
API documentation comment.

Looking around I don't think this was documented in CodingGuidelines,
but see bdfdaa4978d (strbuf.h: integrate api-strbuf.txt documentation,
2015-01-16) and 6afbbdda333 (strbuf.h: unify documentation comments
beginnings, 2015-01-16).

This is commonly supported by various tooling, e.g. in GNU Emacs a "/**"
comment is highlighted differently than a "/*" comment
(font-lock-doc-face v.s. font-lock-comment-face).

So e.g. something_followed_by_open_close_parens() in a comment in C code
will be highlighted as a function name with a "/**" comment, but not
with a "/*" comment. I imagine that the same is true of various other
editors/tooling.