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

On Thu, Apr 21, 2022 at 09:12:10PM +0200, Victor Toso wrote: > 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. Oh, I hadn't even considered that as a possibility but it does indeed look promising. We'd have to see how it look in practice to actually judge though. Maybe you can prototype that after we're done with this series, if you feel like it? :)