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.

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/ :| -- libvir-list mailing list libvir-list(a)redhat.com https://www.redhat.com/mailman/listinfo/libvir-list