Re: [PATCH 05/10] evolve: add the change-table structure

From: Phillip Wood <phillip.wood123@gmail.com>
Date: Sep 28, 2022, 14:33 UTC
Message-ID: <72c4e8c9-62bb-96aa-7b42-d7103b7873eb@dunelm.org.uk>
In-Reply-To: <220927.861qrwzvhe.gmgdl@evledraar.gmail.com>

On 27/09/2022 16:28, Ævar Arnfjörð Bjarmason wrote:

Show 31 quoted lines

> 
> On Tue, Sep 27 2022, Phillip Wood wrote:
> 
>> On 27/09/2022 14:50, Ævar Arnfjörð Bjarmason wrote:
>>> On Tue, Sep 27 2022, Phillip Wood wrote:
>>>
>>>> On 23/09/2022 19:55, Stefan Xenos via GitGitGadget wrote:
>>>>> +/**
>>>>
>>>> We tend to just use '/*' rather than '/**'
>>> No, we use both, and /** is correct here. It's an API-doc syntax,
>>> see
>>> e.g. strbuf.h.
>>> It's explicitly meant for this sort of thing, i.e. comments on
>>> public
>>> structs in a header & the functions in a header (and struct members,
>>> etc.).
>>
>> We don't do that consistently, we don't mention them in
>> CodingGuidelines and we don't use anything that processes API-doc
>> comments. It would be a lot simpler and it would be consistent with
>> our coding guidelines just to use the same style everywhere. That
>> would avoid problems where this series uses API-doc comments for
>> in-code comments in .c files and where single line comments in header
>> files do not use the API-doc syntax.
> 
> Yes, this isn't documented in CodingGuidelines (but FWIW is in various
> commit messages).
> 
> I'm pointing out that this isn't a mistake, but the preferred style for
> new API docs.

It seems a bit a stretch to call it the preferred style, however I had thought all our uses were historic but that's not the case.

Chris if you want to use '/**' style comments for the API docs then please do so consistently and do not use them elsewhere.

> At least Emacs knows how to highlight these differently, which is the
> main use I personally get out of them, I don't know what other use-cases
> there are for them...

I've come across them in projects that use gtk-doc or other documentation generators where it is necessary to distinguish 'documentation' from 'code comments'. I don't think they add much value if one is not generating documentation from the source, it is just one more thing for contributors to remember.

Best Wishes

Phillip