Re: Transfer rules of inout parameters

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


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


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

Philip C

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]