Re: Transfer rules of inout parameters

[philip chimento gmail com]

Well, that would be a good answer to Philip's

On Fri, Feb 9, 2018 at 4:47 AM Christoph Reiter <reiter christoph gmail com> wrote:

On Fri, Feb 9, 2018 at 12:31 PM, Philip Withnall <philip tecnocode co uk> wrote:
>  • Instead, allow separate annotations for the ‘in’ and ‘out’ modes for
> a parameter; something like (in (nullable) (transfer none)) (out (not
> nullable) (transfer full)).
>  • That’s because quite a few of the annotations could theoretically
> differ between the modes: nullability, transfer and array length.
>  • Because this is tricky to reason about, don’t have a default:
> require that everything is always specified for inout parameters.
>  • My suggested syntax is horrible.

Somewhat related, having two separate descriptions for in/out would
also be nice for the binding documentation as the in and out parts get
split into a parameter and a return value, each needing their own
description. For example with gtk_init_check [0] this currently
results in a confusing duplicated description which focuses on the C
value type instead of the actual values being transferred [1].

[0] https://gitlab.gnome.org/GNOME/gtk/blob/3.22.26/gtk/gtkmain.c#L1073
[1] https://lazka.github.io/pgi-docs/#Gtk-3.0/functions.html#Gtk.init_check

That would have the added bonus of being a good improvement to Philip W's suggested syntax.

Example:

/**
 * gtk_init_check:
 * @argc: (in) (transfer none): Address of the `argc` parameter of
 *     your main() function (or 0 if @argv is %NULL).

 * @argc: (out) (transfer none): If any arguments were handled, this is

 *     the new length of @argv. If not, same as @argc passed in.

 * @argv: (array length=argc) (in) (allow-none) (transfer none): Address

 *     of the `argv` parameter of main(), or %NULL.

 * @argv: (array length=argc) (out) (transfer none): The array @argv

 *     that was passed in, with any options understood by GTK+ stripped.

 * ...

Writing this fictional doc-comment I can see that it would be nice, but not essential, to be able to specify whether you are using the text `@argc` to refer to the in or out parameter.

Regards,

Philip C