Re: [libvirt] How to generate better API documentation?
On 16.01.2017 08:24, Michal Privoznik wrote:
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.
Also, there is no link validation. For instance, I'm going through our
network docs [3] reading about trustGuestRxFilters. And the paragraph
links non-existent anchor #elementSNICS in domain XML page.
While this one can be fixed easily, checking for others would be a waste
of time.
Michal
3: http://libvirt.org/formatnetwork.html#elementsMetadata