[Spice-devel] Gtk-doc VS Doxygen

[Daniel P. Berrange]

On Fri, May 20, 2016 at 06:44:01AM -0400, Frediano Ziglio wrote:
> Hi,
>   I'd like to have some standard on the internal documentation of spice-server.
> 
> The current situation is quite messy having different styles.
> I think the worst think is not having any documentation, so better messy
> than nothing.
> I really like Doxygen as it's really complete tool however my Gtk-doc knowledge
> is very low and I cannot compare the two.
> I know we use quite a lot of "G" stuff so perhaps people feels more comfortable
> with Gtk-doc.
> I'd like to see the documentation generated and possibly published on web
> so suggestion from the guys who maintain the website are really welcome.

IMHO i'd always use gtk-doc for API documentation for any codebase which is
based on glib, especially if you start to use GObject in any way, as it opens
the door to trivially support gobject introspection in the future as it uses
the same annotations.

>From the POV of a developer consuming the API documentation I find the Doxygen
HTML fairly unpleasant to read - the GTK-DOC style/layout feels (subjectively)
more user friendly.

Ultimately though any documentation is better than no documentation and the
real hard work is writing the good quality docs, regardless of format :-)

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