Re: [PATCH] documentation, 3er try

[Alexander Larsson <alexl redhat com>]

On 14 Dec 2002, Diego González wrote:

> On Fri, 2002-12-13 at 00:03, Malcolm Tredinnick wrote:
> > More comments ...
> > 
> > On Thu, Dec 12, 2002 at 12:01:45PM +0100, Diego González wrote:
> > > this is a new documentation patch, with the suggestions from Malcolm
> > > incorporated:
> > > 
> > > Switch to use libxslt to generate the help 
> > > Check for gtk-doc >= 0.10
> > > Inline the documentation in header files
> > > Marked some of the functions added in the 2.2 dev cicle with 
> > > "Since: 2.2", so that it shows in the documentation
> > > Added help for some enums and functions.
> > > 
> > > I have regenerated the help in my computer and it seems to work. 
> > 
> > You have added --sgml-mode to MKDB_OPTIONS (in doc/Makefile.am) and that
> > was not there previously. You now have to go through every single
> > documentation comment and check that all "special" characters are marked
> > up as the appropriate entities (e.g. '>' in a comment must now be >,
> > etc). It would really be better to not introduce this option unless you
> > are have checked every single comment.
> > 
> > Does 'make distcheck' really pass? It seems like you have not changed
> > the dist-hook rule in doc/Makefile.am, so it will still look in
> > doc/sgml, rather than doc/xml in some casesi (look at line 199 in the
> > current CVS doc/Makefile.am). I may be wrong about this one (don't have
> > a gnome-vfs build around to check it with at the work at the moment),
> > but that has needed to be changed everywhere else, so I don't see why
> > gnome-vfs would be different.
> 
> ok, i have changed all of this, hope it is ok :-)

I'm not very good at this docs stuff, and I'd like for malcolm to check it 
over, but some points:

+AC_SUBST(HAVE_GTKDOC)
HAVE_GTKDOC doesn't seem to be set anywhere.

-        <listitem<para>>Return the
+        <listitem><para>>Return the

That >> doesn't look right.

+/**
+ * gnome_vfs_open_fs:
+ * @handle:
+ * @filedes:
+ * 
+ *
+ * Return Value:
+ *
+ * Since 2.2
+ **/

Could be e.g:

+/**
+ * gnome_vfs_open_fs:
+ * @handle:  A pointer to a pointer to a GnomeVFSHandle object
+ * @filedes: a unix file descriptor
+ * 
+ * Converts an open unix file descriptor into a GnomeVFSHandle that 
+ * can be used with the normal GnomeVFS file operations. When the handle
+ * is closed the file descriptor will also be closed.
+ *
+ * Return Value: %GNOME_VFS_OK if the open was ok, a suitable error otherwise.
+ *
+ * Since 2.2
+ **/

-- 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 Alexander Larsson                                            Red Hat, Inc 
                   alexl redhat com    alla lysator liu se 
He's an oversexed soccer-playing grifter haunted by an iconic dead American 
confidante She's a violent kleptomaniac lawyer with a knack for trouble. They 
fight crime!