Re: gtk-doc 1.4 changes

[Stefan Kost <kost imn htwk-leipzig de>]

Hi hi,

<snip>
>>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"};
> 
Thats why I though about some extra syntax to denote that the comment contains
the short/long desc for the respective section. What about:
/**
 * Basic Types|Long Desc:
 */

Anyway I will look in the sources to understand better how it does looking up
the doc-fragments.

> 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!
>  */ 
> 

Here the problem is that we need something for the long term. The problem is
that in this case we *tell* gtk-doc that it should not be smart and detect that
something is an enum or struct or what ever, but use a differenct document
class. Then we can define things like ENVVAR, CONFIGFILE, <WHATEVER> and specify
e.g. that this define actually is-a CONFIGFILE. So just adding a '$' is not
sufficient, but e.g.
/**
  * $ENVAR::HOME:
  *
  * Your home directory, stupid!
  */

would do.

After all the main problem is that gtk-doc has no real grammar, that can easilly
be extended. I would like to use special chars carefully, so that we don't need
to require UTF-8 sources soon, only to have enough special chars for all the
purpose markup. ;)

Stefan