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
