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 <sxenos@xxxxxxxxxx> >>>> 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 <sxenos@xxxxxxxxxx> >>>> Signed-off-by: Chris Poucet <poucet@xxxxxxxxxx> >>> >>>> 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...
