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

- From: Ævar Arnfjörð Bjarmason \<hidden\>
- Date: 2022-09-27 15:29:56 
- List: git
- Page: https://ratatoskr.run/git/2022/09/7956777
- Thread: https://ratatoskr.run/git/2022/09/7956579/t.md

```text

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:
>>>> From: Stefan Xenos <redacted>
>>>> A change table stores a list of changes, and supports efficient
>>>> lookup
>>>> from a commit hash to the list of changes that reference that commit
>>>> directly.
>>>> It can be used to look up content commits or metacommits at the head
>>>> of a change, but does not support lookup of commits referenced as part
>>>> of the commit history.
>>>> Signed-off-by: Stefan Xenos <redacted>
>>>> Signed-off-by: Chris Poucet <redacted>
>>>
>>>> diff --git a/change-table.h b/change-table.h
>>>> new file mode 100644
>>>> index 00000000000..166b5ed8073
>>>> --- /dev/null
>>>> +++ b/change-table.h
>>>> @@ -0,0 +1,132 @@
>>>> +#ifndef CHANGE_TABLE_H
>>>> +#define CHANGE_TABLE_H
>>>> +
>>>> +#include "oidmap.h"
>>>> +
>>>> +struct commit;
>>>> +struct ref_filter;
>>>> +
>>>> +/**
>>>
>>> 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.

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

```