On Sat, 2002-12-07 at 00:53, Malcolm Tredinnick wrote: > On Fri, Dec 06, 2002 at 04:08:02PM +0100, Diego González wrote: > > this patch cleans up documentation in gnome-vfs-xfer.[c-h], mainly i > > just took out the documentation of the enums from gnome-vfs-xfer.h and > > put it into tmp/gnome-vfs-xfer.sgml, this is the same that gtk docs do. > > In general, I think it is better to have the enum documentation inline > (i.e. in the header file). that way, it is also visible when somebody > just looks at the installed header file on their machine and it is close > to the code it is documenting (saves developers having to remember to > change two files when they change the enum). > > Note that the feeling on gtk-doc list is to move as much as possible to > inline documentation and just use the tmpl files for truly exceptional > cases. Some of these facilities have only been available recently, > though, which is why modules that have documented since the dawn of time > (e.g. gtk+) do not always use the latest features (and are not even > internally consistent sometimes). > > I am against this portion of the patch (not that my opinion carries any > weight, but I thought I would get people thinking about it). > i just redid this even before reading your answer. It seemed better, I will resend the patch on sunday, i'm leaving for the weekend. I have cleaned up some of the documentation. > > Also i migrated the way to built the documentation from sgml to xml, > > this has been also done in gtk. > > This patch is not correct at the moment. You need to change configure.in > to correctly detect gtk-doc >= 0.10. See desktop-devel or gtk-doc lists > for some sample code that will do this (or have a look at gtk+ again). > In some modules there are other change required to the Makefile.am in > the docs directory, too (not just adding the --output-format=xml > option). Did you run a completely rebuild after your patch was applied > (from autogen.sh up to 'make distcheck')? > i didn't run distcheck, but i rebuilt the documentation. > Sometimes the sgml-build.stamp rule needs changing (removing the > --main-sgml-file option). Also, the dist-hook rule needs to copy files > from the xml/ directory, not the sgml/ directory in this build mode. > ok, i'll check that. > Cheers, > Malcolm -- Diego González <diego pemas net>
Attachment:
signature.asc
Description: This is a digitally signed message part