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