idea on gobject-introspection / gtk-doc metadata

[Dan Winship <danw novell com>]

One of the gobject-introspection TODOs is:

    - Write a scanner to create XML from annotated headers

AFAIK, no one has put forward any suggestions about what those 
annotations would be. gtk-sharp's parser already figures out a lot of 
things (by assuming that the code obeys certain conventions), but there 
are lots of other things that can't really be guessed in most cases 
(like memory management conventions, or whether an int* is an out arg, 
an in-out arg, or an array).

Meanwhile, on desktop-devel-list, there was some discussion about 
requiring all new APIs to be documented when they're added to the 
platform, and more generally about how to get hackers to be better about 
documenting APIs more.

And then on the wiki 
(http://live.gnome.org/IdealDeveloperDocumentation), someone suggested:

    It would be great to make it easier to generate documentation for
    language bindings from the same sources as the C docs... For example
    having an annotation to indicate that a sentance/paragraph applies
    only to C (since it refers to C-isms like memory management issues)
    would make the docs easier to translate for other languages.


So, what if we made it so that the extra annotations needed to generate 
correct gobject-introspection metadata go into the gtk-doc comments 
(thus encouraging people to write API docs, because it's essentially 
necessary to get working introspection data), and further made it so 
that the metadata was written in such a way that you can tell that 
certain parts of the documentation are directly related to certain 
pieces of metadata, which might therefore make them irrelevant in other 
language bindings. Eg:

/**
 * gtk_tree_selection_get_selected_rows:
 * @selection: A #GtkTreeSelection.
 * @model:[[direction="out"]] A pointer to set to the #GtkTreeModel, or
 * %NULL.
 *
 * Creates a list of path of all selected rows. Additionally, if you are
 * planning on modifying the model after calling this function, you may
 * want to convert the returned list into a list of
 * #GtkTreeRowReference<!-- -->s. To do this, you can use
 * gtk_tree_row_reference_new().
 *
 * Return value: A #GList<GtkTreePath> containing a #GtkTreePath for
 * each selected row. [[transfer="full"] You must free each element of
 * the list with gtk_tree_path_free() and then free the list itself with
 * g_list_free().]
 *
 * Since: 2.2
 **/

From this, the scanner learns that the "model" parameter is 
direction="out" and null-ok="1" (because the description contains "or 
%NULL"), and the returned GList contains GtkTreePaths and is 
transfer="full".

The new-and-improved gtk-doc parser would ignore the "<GtkTreePath>" 
after "#GList", and would mark the "[[transfer="full"] ...]" part in the 
output in some way that wouldn't affect the standard html docs at all, 
but could be used by another doc postprocessor to strip out that 
sentence, since it refers to memory-management stuff that isn't relevant 
to some bindings.

Maybe the specific syntax here sucks, and there are still some further 
improvements that could be made to the idea, but I wanted to throw it 
out as a possibility.

-- Dan