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

[Victor Toso]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20220421/2d0fe95b/attachment.sig>