On Mon, May 20, 2019 at 03:41:08PM -0300, Eduardo Habkost wrote: > Please welcome GSoC student Gabriel Barreto. Gabriel is going to > work on QEMU API Documentation Generation[1]. > > Gabriel's first task is to evaluate our options for extract doc > comments from C source code and integrate them into Sphinx > documentation. I saw that Peter has experimented with kernel-doc > in the past[2][3]. Has anybody evaluated other alternatives? > (e.g. Hawkmoth[4])
In the past I tested both GTK-DOC and Doxygen. GTK-DOC has assumptions that you're following "normal" GTK/GLib style and can't cope with many C type decls if you diverge, which rules it out on practical grounds. Doxygen can parse more or less anything which I really dislike the output structure it generates for docs as it is not at all friendly to browser and find the info you actually want compared to other docs tools Hawkmoth seems pretty attractive in its output format, but doesn't appear to be part of either Debian or Fedora distros, so we would have to bundle it in QEMU I expect. My big concern there is that there have only been 2 contributors to Hawkmoth in its entire 3 year existance, which makes me fear for its long term viability if the main author gives up. QEMU should pick a tool which is well established / widely used & thus stands a good chance of being maintained for the long term, as we don't want to end up relying on abandonware in 5 years time. The kernel-doc project is not widely used, but its main user is significant enough that it isn't likely to die through lack of maintainers. If we're using sphinx for the rest of our docs, then I think it is pretty compelling to have a docs tool that integrates well with sphinx. I personally don't care much about the source comment annotation syntax. It is mostly just a matter of bikeshed colour picking, and no matter which tool we pick will require updates to the source. The style / layout / readability of the output is more important to me. > [1] > https://wiki.qemu.org/Google_Summer_of_Code_2019#API_documentation_generation > [2] https://www.mail-archive.com/qemu-devel@nongnu.org/msg411643.html > [3] https://www.mail-archive.com/qemu-devel@nongnu.org/msg411841.html > [4] https://readthedocs.org/projects/hawkmoth/ Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
