Hi, On Thu, Apr 21, 2022 at 11:45:05AM -0700, Andrea Bolognani wrote: > On Thu, Apr 21, 2022 at 08:34:10PM +0200, Victor Toso wrote: > > Not sure I understood what is preferable. For all functions and > > typdefs and macros, it should be: > > > > Line > > 1 /** > > 2 * type_name: > > 3 * > > 4 * Maybe some comment. > > 5 * > > 6 * Maybe something about return value. > > 7 * > > 8 * Since: v1.2.3 > > 9 * > > 10 */ > > > > Do you suggest to not have empty line 9 ? > > Correct.
Got it.
> > For enum values, if they are multiple line comments, I try to
> > follow the above too. Otherwise, to avoid adding lots of extra
> > empty lines around where we only had a single line as comment
> > before, I've only appended the Since tag.
>
> Yeah, that sounds sensible. I think it would be nice to use the
> same multi-line, documentation-right-above-symbol style
> everywhere, but it would most likely become too unwieldy in
> practice, especially for large enums.
Yeah. I'd instead suggest to move documentation to the top of
typedef enum, in a similar fashion of what qemu/qapi schema does.
https://github.com/qemu/qemu/blob/master/qapi/audio.json#L13
Documentation is kept close enough of the data type without
polluting the surround definitions, etc. At the very least, it
would use less empty lines... I think.
Cheers,
Victor
signature.asc
Description: PGP signature
