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