Re: Private virtual methods

[Emmanuele Bassi <ebassi gmail com>]

On Sun, 5 Aug 2018 at 16:30, Philip Chimento via gir-devel-list <gir-devel-list gnome org> wrote:

 

OK, what I didn't realise was that the way to document virtual methods is as members of the class, which sounds obvious now. Is it important to document all virtual methods this way, or are the tools that generate gir and typelib files able to deduce the presence of function pointer class members if you use the "virtual" annotation on the corresponding public functions?

The vfunc slot will be deduced in any case by g-ir-scanner, so it will be present whether you document it or not.

About annotating the function pointer types, as far as I know this is a gap in GI's capabilities.

Annotating the vfunc inside the structure works for both classes and interfaces. See, for instance, GListModel's get_item() virtual function:

```

/**
 * GListModelInterface::get_item:
 * @list: a #GListModel
 * @position: the position of the item to fetch
 *
 * Get the item at @position. If @position is greater than the number of
 * items in @list, %NULL is returned.
 *
 * %NULL is never returned for an index that is smaller than the length
 * of the list.  See g_list_model_get_n_items().
 *
 * Returns: (type GObject) (transfer full) (nullable): the object at @position.
 * Since: 2.44
 */
```

Which generates this introspection XML:

```

      <virtual-method name="get_item" version="2.44">
        <doc xml:space="preserve">Get the item at @position. If @position is greater than the number of
items in @list, %NULL is returned.

%NULL is never returned for an index that is smaller than the length
of the list.  See g_list_model_get_n_items().</doc>
        <return-value transfer-ownership="full" nullable="1">
          <doc xml:space="preserve">the object at @position.</doc>
          <type name="GObject.Object" c:type="gpointer"/>
        </return-value>
        <parameters>
          <instance-parameter name="list" transfer-ownership="none">
            <doc xml:space="preserve">a #GListModel</doc>
            <type name="ListModel" c:type="GListModel*"/>
          </instance-parameter>
          <parameter name="position" transfer-ownership="none">
            <doc xml:space="preserve">the position of the item to fetch</doc>
            <type name="guint" c:type="guint"/>
          </parameter>
        </parameters>
      </virtual-method>
```

The syntax is `StructureName::virtual_function`.

Ciao,

 Emmanuele.

--

https://www.bassi.io
[@] ebassi [@gmail.com]