Re: Short & long description sections.

[Owen Taylor <otaylor redhat com>]

Oisin Boydell <Oisin Boydell Sun COM> writes:

> I am documenting the gnome atk accessability toolkit using gtk-doc to generate 
> the html API reference.
> Is it correct that the text for the short and long desciption settings which 
> appears in the final generated html files must be added to the sgml files in the 
> tmpl directory after the 'make templates' step?
>
> Or is it possible to add the descriptions in the source code as a comment block 
> and have gtk-doc automatically extract the descriptions (in the way it extracts 
> function descriptions, parameter descriptions etc.)?
> If so, what format should the long and short descriptions be written in comment 
> blocks in source files (are tags such as 'description:' or '@description:' 
> used)?

Currently there is no way of doing short and long descriptions inline. 

(And it isn't clear that this would be a good idea - since editing
large amounts of SGML markup in a comment would probably be annoying.)
The expectation is that you put it into the tmpl/ files - which are supposed
to be checked into CVS.

While the template files are automatically generated the first time,
subsequent 'make templates' steps will merge any changes into the
existing template files.

Regards,
                                        Owen