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 _______________________________________________ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
