idea on gobject-introspection / gtk-doc metadata

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
