Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation

["Daniel P. Berrangé" <berrange@redhat.com>]

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 :|