Re: [PATCH v3 13/30] docstring: function: libvirt: Add 'Since version' metadata

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