Re: gtk-doc 1.4 changes

[Matthias Clasen <mclasen redhat com>]

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.

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


The problem with the short and long descriptions is that we can't really
assume a neat OO design where every section documents a class (think
about GLib, no classes anywhere). Therefore, gtkdoc-mkdb keys the
descriptions off the template filenames:

    my $short_desc = $SymbolDocs{"$TMPL_DIR/$file:Short_Description"};

One approach would be to add section ids to the $MODULE-section.txt
files, and then use these to look up the short and long descriptions. 
In order to spare people the burden of adding tons of ids to their
section.txt files, we should probably fall back to the <FILE> of the
section. So for

<SECTION>
<TITLE>Basic Types</TITLE>
<FILE>types</FILE>

we would use a key like types/Short_Description (we have to insert some
kind of special characters like / here in order to avoid clashing with
other keys used in $SymbolDocs).

But we would allow to override the key using something like

<SECTION>
<ID>basic_types</ID>
<TITLE>Basic Types</TITLE>
<FILE>types</FILE>

(Maybe this override isn't even necessary...)


> Further Brian expressed the wish to specify things like an
> #define describing an envvar.
> So we need either a prefix and a delimiter
>  * ENVVAR=DISPLAY_ENV_VAR:
>  * SHORT_DESC=CLASSNAME:
> or something that uses a prefix like
>  * DISPLAY_ENV_VAR.ENVVAR:
>  * CLASSNAME.SHORT_DESC:
> or a new keyword like
>  * DISPLAY_ENV_VAR:
>  * Type: Envvar
> 

I'm not opposed to allowing to document environment variables, but
you have to consider how you can list them in the section.txt file 
without clashing with other symbols. A suggestive syntax for doc 
comments might be:

/**
 * $HOME:
 *
 * Your home directory, stupid!
 */ 


Matthias