[libvirt] How to generate better API documentation?
Michal Privoznik
mprivozn at redhat.com
Mon Jan 16 07:24:25 UTC 2017
Dear list,
now that we more or less agreed to use some new features (i.e. automatic free() when a variable goes out of the scope [1]), and with our NEWS efforts, do you think it is finally the right time to fix generation of our API docs too?
What I mean? Look here: [2] People use '@variable' notation hoping that the generator will put a link there. Or that our generator would allow us to:
typedef enum {
A = X,
B = Y,
C = Z,
# ifdef VIR_ENUM_SENTINELS
VIR_ENUM_LAST
# endif
} virEnum;
where X, Y, Z come from another enum.
Long story short, our documentation generator has a lot of bugs. What if instead of putting our effort in fixing it we would switch to something that is already available on the market? gtk-doc, doxygen, etc. Personally, I don't have any preference. Just want to know what your opinion is.
Again, if I get a green light I can put it onto the list of GSoC projects [3].
Michal
1: https://www.redhat.com/archives/libvir-list/2017-January/msg00323.html
2: http://libvirt.org/html/libvirt-libvirt-domain.html#virConnectDomainEventBlockJobCallback
3: http://wiki.libvirt.org/page/Google_Summer_of_Code_2017
More information about the libvir-list
mailing list