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

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-... > > 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.

> > (...) 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.

> > 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!