Re: Transfer rules of inout parameters

[Philip Withnall <philip tecnocode co uk>]

On Sun, 2018-02-11 at 22:23 +0000, philip chimento gmail com wrote:
> Well, that would be a good answer to Philip's 
>
> On Fri, Feb 9, 2018 at 4:47 AM Christoph Reiter <reiter.christoph@gma
> il.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#L
> > 1073
> > [1] https://lazka.github.io/pgi-docs/#Gtk-3.0/functions.html#Gtk.in
> > it_check
>
> That would have the added bonus of being a good improvement to Philip
> W's suggested syntax. 

Agreed, that would be nice.

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

How about:

/**
 * gtk_init_check:
 * @argc.in: (in) (transfer none): Address of the `argc` parameter of
 *     your main() function (or 0 if @argv is %NULL).
 * @argc.out: (out) (transfer none): If any arguments were handled,
 *     this is the new length of @argv.out. If not, same as @argc.in
 *     passed in.
 * …
 */

Then you could use @argc.in and @argc.out to refer to the different
modes of @argc in the documentation body. It also means that all the
parameter names in the list at the top of the documentation comment
would continue to be unique (which probably makes implementation
easier).

Philip W

Attachment: signature.asc
Description: This is a digitally signed message part