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

[Peter Krempa]

On Thu, Apr 21, 2022 at 06:21:06 -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 :)

This patch will need to be modified due to mistakes pointed out in the
patch reviewing the validation script, so the discussion can continue.
> 
> 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.

One more thing to consider is (not visible in this snipped patch as we
see only a typedef) is that we already do have the version info for
functions in the generated API xml. So ... do we even want to be adding
them to the comments?

Obvious pro is that it's visible right from the function comment when
somebody is looking at the code itself.

Obvious con is that there are now multiple places that have this info.

It doesn't change anything for tools consulting the API xml files and
thus also for the web page which is generated from the XML.