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

Andrea Bolognani abologna at redhat.com
Thu Apr 21 17:32:53 UTC 2022


On Thu, Apr 21, 2022 at 04:04:20PM +0200, Peter Krempa wrote:
> On Thu, Apr 21, 2022 at 06:59:14 -0700, Andrea Bolognani wrote:
> > On Thu, Apr 21, 2022 at 03:42:31PM +0200, Peter Krempa wrote:
> > > 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.
> >
> > I think it makes sense to document version information for all public
> > symbols in the same way.
> >
> > In the case of functions, the other source for this information (the
> > symbols file) can still be parsed and used to double-check that there
> > are no inconsistencies.
>
> Sure and it's actually done in this series, which is great.
>
> We just need a hack for 4 functions where the code was mistakenly added
> in a later version than under which the symbol is exported. (also done
> in this series, just needs to be fixed).
>
> And definitely it's more convenient when looking at the code itself than
> having to fire up the browser and look at the generated docs or in the
> API xml file.

Great, sounds like we're in agreement on the approach then :)

-- 
Andrea Bolognani / Red Hat / Virtualization



More information about the libvir-list mailing list