[libvirt] How to generate better API documentation?

[Daniel P. Berrange]

On Mon, Jan 16, 2017 at 08:24:25AM +0100, 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.
> 
> 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.

To me the key factor is what the end result looks like, how easy it is to
navigate & find stuff. From that POV doxygen is ruled out as the HTML it
generates is just awful - I despair every time i find a project which has
use doxygen for its API docs :-(

gtk-doc is pretty good in this respect, but the limitation is that they do
not try to support every possible C style - they expect you to write code
in a gobject like style. I can't tell offhand if libvirt is close enough
to work with gtk-doc or not - I do know that QEMU failed. It is something
you'd just have to try and see if it works, and also see if the result is
better than what we have of course.

> Again, if I get a green light I can put it onto the list of GSoC projects [3].

I'm not sure this is  a good idea, because I think there's a high chance
that you'd start the effort only to determine we should stick with what
we have already, which would not make for a hugely successful GSoC project.

Regards,
Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://entangle-photo.org       -o-    http://search.cpan.org/~danberr/ :|