Re: gtk-doc 1.4 changes

[Damon Chaplin <damon karuna uklinux net>]

On Tue, 2005-01-11 at 15:41, Matthias Clasen wrote:
> On Tue, 2005-01-11 at 16:19 +0100, Stefan Kost wrote:
> > hi all,
> > 
> > I volunteer to dedicate the next weekend to do some gtk-doc patches. Please
> > comment on the suggestions:
> > 
> > 1.) currently <INCLUDE> in sections.txt automatically adds '<>' around the
> > include file name. I would like to change the behaviou that it does *not* do
> > this, when the include file name is enclosed in '""'.
> > I need this when documenting the object classes of an application. These
> > includes don't get installed and are included as e.g. #include "bt-edit.h"
> > 
> > 2.) add symbols where members are undocumented to the undocumented file.
> > 
> > 3.) try to see if I can detect undocumented short and long descriptions. I would
> > like to see those listed in the undocumented file as well.
> 
> These sound fine to me.

I agree.


> > 4.) a major point on my list is to add the possibillity to get rid of the
> > template files. I would really like to add  short and longs descriptions in the
> > sources. I do gtk-doc cleanup for gstreamer and there I learned - core
> > developers edit code, but not template files :(.
> > I repeat the thoughts here:
> > We need a syntax for gtk-doc that it can detect that a comment is for the short
> > and long-desc.

(gtk-doc syntax is horrible. If I'd known it would be used for all GNOME
API docs I might have thought about it a little.)


We already have 2 special types of symbols, properties and signals, e.g.
   GtkAction::activate
   GtkAboutDialog:authors

We now need section short/long descriptions, envvars & files (& maybe
gconf keys at some point).

I think we could just use "SECTION:gtkaboutdialog", "ENVVAR:HOME" and
"FILE:stdio.h".

The part after the "SECTION:" would be the section filename (basically
just an id). It could default to the current filename, without the '.c'
suffix.

For the SECTION docs we could keep the short & long description
together, e.g.

/**
 * SECTION:gtkaboutdialog
 * @summary: Display information about an application
 *
 * The #GtkAboutDialog offers a simple way to display information
 * about a program like its logo, name, copyright, website and license.
 */

The @summary would be the short description. Is there a better word to
use?

Damon