idea on gobject-introspection / gtk-doc metadata
- From: Dan Winship <danw novell com>
- To: gtk-devel-list gnome org
- Cc: gtk-doc-list gnome org
- Subject: idea on gobject-introspection / gtk-doc metadata
- Date: Wed, 21 Sep 2005 11:18:53 -0400
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:
* @selection: A #GtkTreeSelection.
* @model:[[direction="out"]] A pointer to set to the #GtkTreeModel, or
* 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
* 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
* 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
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.
] [Thread Prev