Re: Documentation fixes

[Malcolm Tredinnick <malcolm commsecure com au>]

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).

> 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')?

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.

Cheers,
Malcolm

-- 
He who laughs last thinks slowest.