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

- From: Phillip Wood \<hidden\>
- Date: 2022-09-28 14:33:08 
- List: git
- Page: https://ratatoskr.run/git/2022/09/7956891
- Thread: https://ratatoskr.run/git/2022/09/7956579/t.md

```text
On 27/09/2022 16:28, Ævar Arnfjörð Bjarmason wrote:
>
> 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


```