Re: gtk-doc 1.4 changes

[Matthias Clasen <mclasen redhat com>]

On Wed, 2005-01-12 at 14:31 +0000, Damon Chaplin wrote:

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

Sounds good enough to me. To map this to the sections defined
in sections.txt, we can use the <FILE>foo</FILE> which is already used
in sections.txt.

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

Yes, I had the same idea, and "summary" seems to be a good name. Doing
things this way also encourages people to keep the short description
short.

Matthias