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

[Victor Toso]

Hi,

On Thu, Apr 21, 2022 at 06:21:06AM -0700, Andrea Bolognani wrote:
> On Wed, Apr 20, 2022 at 09:08:02PM +0200, Victor Toso wrote:
> > @@ -4815,6 +4821,9 @@ typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn,
> >   *
> >   * The callback signature to use when registering for an event of type
> >   * VIR_DOMAIN_EVENT_ID_RTC_CHANGE with virConnectDomainEventRegisterAny()
> > + *
> > + * Since: v0.8.0
> > + *
> >   */
> >  typedef void (*virConnectDomainEventRTCChangeCallback)(virConnectPtr conn,
> >                                                         virDomainPtr dom,
> > @@ -4853,6 +4862,9 @@ typedef enum {
> >   * The callback signature to use when registering for an event of type
> >   * VIR_DOMAIN_EVENT_ID_WATCHDOG with virConnectDomainEventRegisterAny()
> >   *
> > + * Since: v0.8.0
> > + *
> > + *
> >   */
> >  typedef void (*virConnectDomainEventWatchdogCallback)(virConnectPtr conn,
> >                                                        virDomainPtr dom,
> 
> I see that Peter is going really hard with these reviews, so while I
> intended to look at the series before the end of the week he's
> probably going to be done with it way before then so I better speak
> up now :)
> 
> The vertical whitespace is inconsistent: two different styles
> can be seen here, and I've also spotted instances of
> 
>   * ...
>   *
>   * Since: v...
>   */
> 
> elsewhere.
> 
> My own preference would be to adopt this last style everywhere, but
> I would be okay with having a single empty line after version
> information. Either way, it needs to be applied consistently.

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 ?

I'll try to re-review all of them again. I do enjoy keeping
things consistent as well.

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.

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/45234f69/attachment.sig>