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
Attachment:
signature.asc
Description: PGP signature
