Re: [Spice-devel] Gtk-doc VS Doxygen
> > On Wed, 2016-05-25 at 10:21 +0200, Pavel Grunt wrote: > > Hi, > > > > On Fri, 2016-05-20 at 06:44 -0400, Frediano Ziglio wrote: > > > Hi, > > > I'd like to have some standard on the internal documentation of spice- > > > server. > > > > > Yes, that would be nice. > > > > > 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. > > > > "GTK-Doc has some special code to document the signals and properties of > > GTK+ > > widgets and GObject classes which other tools may not have." [0] > > This is a big one. I know that doxygen has some nice features that gtk-doc > may > not, but for any project using GObject I think gtk-doc is pretty much > essential. > It makes it simple to document signals, properties, and GObject inheritance > where other tools would not really understand these concepts. > I think they are quite fair, in the same page "For a more polished general-purpose documentation tool you may want to look at Doxygen." bye the way, as I cannot compare the two 3 people over 3 prefer Gtk-doc so it's decided! Frediano > > > > > But I think the same can be achieved with Doxygen. > > > > > 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. > > > > Both Doxygen and gtk-doc can be used. We are using gtk-doc for spice-gtk, > > it > > is > > not planned to switch to something else. > > > > [0] http://www.gtk.org/gtk-doc/ > > > > Pavel ___ Spice-devel mailing list Spice-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/spice-devel
Re: [Spice-devel] Gtk-doc VS Doxygen
On Wed, 2016-05-25 at 10:21 +0200, Pavel Grunt wrote: > Hi, > > On Fri, 2016-05-20 at 06:44 -0400, Frediano Ziglio wrote: > > Hi, > > I'd like to have some standard on the internal documentation of spice- > > server. > > > Yes, that would be nice. > > > 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. > > "GTK-Doc has some special code to document the signals and properties of GTK+ > widgets and GObject classes which other tools may not have." [0] This is a big one. I know that doxygen has some nice features that gtk-doc may not, but for any project using GObject I think gtk-doc is pretty much essential. It makes it simple to document signals, properties, and GObject inheritance where other tools would not really understand these concepts. > > But I think the same can be achieved with Doxygen. > > > 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. > > Both Doxygen and gtk-doc can be used. We are using gtk-doc for spice-gtk, it > is > not planned to switch to something else. > > [0] http://www.gtk.org/gtk-doc/ > > Pavel > > > > Frediano > > ___ > > Spice-devel mailing list > > Spice-devel@lists.freedesktop.org > > https://lists.freedesktop.org/mailman/listinfo/spice-devel > ___ > Spice-devel mailing list > Spice-devel@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/spice-devel ___ Spice-devel mailing list Spice-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/spice-devel
Re: [Spice-devel] Gtk-doc VS Doxygen
Hi, On Fri, 2016-05-20 at 06:44 -0400, Frediano Ziglio wrote: > Hi, > I'd like to have some standard on the internal documentation of spice- > server. > Yes, that would be nice. > 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. "GTK-Doc has some special code to document the signals and properties of GTK+ widgets and GObject classes which other tools may not have." [0] But I think the same can be achieved with Doxygen. > 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. Both Doxygen and gtk-doc can be used. We are using gtk-doc for spice-gtk, it is not planned to switch to something else. [0] http://www.gtk.org/gtk-doc/ Pavel > > Frediano > ___ > Spice-devel mailing list > Spice-devel@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/spice-devel ___ Spice-devel mailing list Spice-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/spice-devel
Re: [Spice-devel] Gtk-doc VS Doxygen
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 :| ___ Spice-devel mailing list Spice-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/spice-devel
[Spice-devel] Gtk-doc VS Doxygen
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. Frediano ___ Spice-devel mailing list Spice-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/spice-devel
