Re: gobject introspection and gtk-doc

[Stefan Kost <ensonic hora-obscura de>]

Hi,
Michael Lawrence wrote:
> Hi,
>
> <snip>
>   
> My idea is, why not annotate the header files (or C) files themselves 
> with this information? It could be integrated with gtk-doc, so that the 
> information could be presented in a standard way in the documentation. 
> For example, there is no standard, fixed way of saying that a parameter 
> is meant as an "out" parameter in the docs. Another example would be 
> whether a return value is owned by the caller. If this stuff was added 
> to the gtk-doc annotations it could be used both for generating metadata 
> blobs as well as the documentation.
>   
If you have some ideas about a possible syntax for gtk, please suggest.
You could also develop this on live.gnome.org [1]. If we have a list of
additional information, a syntax suggestion plus some ideas of how to
represent that in the generated docs, adding this functionality to
gtk-doc should be easy.
> The metadata would require much less human maintenance (perhaps none) 
> and the documentation would be easier to understand by both human and 
> machine. Machine understanding is important when transforming the GTK+ 
> docs while trying to manipulate or filter out information like in/out 
> parameters and memory ownership.
>
> For example, for my language binding RGtk2, I produced R documentation 
> from the GTK+ docs. RGtk2 hides memory management from the user and 
> stuff like "out" parameters are handled very differently in R than in C. 
> It would be nice if this information was included in a machine-readable 
> way in the docs.
>
> Thanks,
>   
> Michael Lawrence
>   
Ciao
  Stfean

[1] http://live.gnome.org/DocumentationProject/GtkDocFuture