Hi, On Tue, Apr 05, 2022 at 04:33:27PM +0000, Andrea Bolognani wrote: > On Tue, Apr 05, 2022 at 01:43:23PM +0200, Victor Toso wrote: > > Differently from the previous patches, we don't parse nor export > > comments associated with variables. This isn't a big deal because we > > only export a single variable: virConnectAuthPtrDefault > > > > Nonetheless, add version field to the exported XML by checking the > > allowlist file. This way, if we add another variable in the future, we > > can simply add it to that file. Calling the function should also warn > > in case we are exporting a new Variable without adding to the file, > > e.g: > > Missing 'Since' tag for: virConnectAuthPtrDefault > > 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.
> 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.
Yes
> 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.
Cheers,
Victor
signature.asc
Description: PGP signature
