Re: idea on gobject-introspection / gtk-doc metadata

[Damon Chaplin <damon karuna uklinux net>]

On Wed, 2005-09-21 at 11:18 -0400, Dan Winship wrote:

> 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".

Personally I'm not too sure this would be a good idea. I think it is
asking a bit too much from developers to add all this stuff. So you'd
probably have to rely on bindings people checking over all the comments.

I also worry that the C documentation may contain references to things
that aren't applicable to language bindings, so you'd have to mark these
as C-only. Then there may be pieces of documentation that should be
added for a specific language binding, so you'd have to add them and
mark them. It might get messier and messier.

Though if lots of language binding maintainers said it would be really
useful I might change my mind.

Maybe a better idea would be for bindings to grab all the gtk-doc
documentation, and then just override the docs for particular functions
if they need to.

Damon