[PATCH v1 4/4] scripts: apibuild: add 'version' to variables

[Victor Toso]

Hi,

On Wed, Apr 06, 2022 at 01:10:40AM -0700, Andrea Bolognani wrote:
> On Tue, Apr 05, 2022 at 08:31:40PM +0200, Victor Toso wrote:
> > On Tue, Apr 05, 2022 at 04:33:27PM +0000, Andrea Bolognani wrote:
> > > I think the fact that we're currently not parsing comments for
> > > variables is just a mistake.
> > >
> > > virConnectAuthPtrDefault seems to be documented in a way that would
> > > be appropriate for the API docs
> >
> > The documentation is not in the headers:
> >
> >     https://gitlab.com/libvirt/libvirt/-/blob/master/include/libvirt/libvirt-host.h#L565
> >
> > Only in the source:
> >
> >     https://gitlab.com/libvirt/libvirt/-/blob/master/src/libvirt.c#L200
> >
> > So, moving the documentation around could be an extra patch,
> > indeed.
> 
> A lot of documentation lives in the .c file, notably that for
> functions. It's perfectly fine for it to be there and it doesn't need
> to be moved.

The suggestion of moving was to address what you pointed out
previously, that users of libvirt can't figure out what that
variable does without digging into the source code.

> > > (...) and the fact that it doesn't show up there means
> > > that users of the library have no way to figure out what
> > > it's there for without digging into the source code, or
> > > even that it exists at all.

So, If it is fine to leave documentation in non
exported/installed source/header files, I'll not be moving them
around.

Next version is just adding Since <version> where the
documentation is, let's see how it goes.

> > > I'd say just start treating comments for variables the same
> > > as those for all other symbols.
> >
> > TBH, because it was only a single exported variable, I didn't
> > put too much effort in parsing the docs, but you made a good
> > point.  I'll try again, to parse comments from exported
> > variables and included it all in the XML API.
> 
> Thanks!

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/20220406/f3890daa/attachment.sig>