Re: clutter - "... int *argc" - their doc entries and corresponding GIArgInfo

[Phil Clayton <phil clayton veonix com>]

Hi,

On 05/05/19 07:31, David Pirotte wrote:
> Hello,
>
> I am working on G-Golf (a guile scheme GI binding library) [1]. I now have a
> 'reasonably good sketch' to work on what will eventually let me 'fully bind' GI
> functions.
>
> While working on this, using Clutter to test, a few questions 'came up', wrt to
> clutter_init and clutter_init_with_args first argument, their respective
> documentation entry and the way GI defines their corresponding GIArg-Info.
>
> 1]      Lets start with the doc quiz:
>
>         ClutterInitError
>         clutter_init (int *argc,
>                       char ***argv);
>
>         ...
>         argc    The number of arguments in argv.        [inout]
>         argv    A pointer       to the array ...                        [inout][allow-none]
>
>
>         ClutterInitError
>         clutter_init_with_args (int *argc,
>                                 char ***argv,
>                                 ...
>
>         ...
>         argc    a pointer to the number of command line arguments.      [inout]
>         argv    a pointer       to the array ...                                                        
> [inout][allow-none]
>
> But I see in an 'old' guile-clutter binding (not using GI), which I can still use, so it
> works fine, that the initialization call is (always):
>
>         if (clutter_init (NULL, NULL) != CLUTTER_INIT_SUCCESS)
>
> Which means that argc is a pointer, that can be NULL, so should the doc entry not be:
>
>         argc    a pointer to the number of command line arguments.      [inout][allow-none]

Noting that allow-none is [deprecated][3] and 'optional' should now be 
used, you would think so, on the grounds that argc and argv are just 
passed through to [g_option_context_parse][4] whose annotations are:

        argc    [inout][optional]
        argv    [inout][array length=argc][optional]

The annotations for [clutter_init][5] are not quite as you have quoted: 
they do include the array annotation on argv:

        argc    [inout]
        argv    [array length=argc][inout][allow-none]

It could be argued that the array annotation (that links argc to argv) 
implicitly means that argc is as optional as argv, so it's not necessary 
to include the 'optional' annotation on argc.  (Bindings that support 
optional inout arguments and combbine argc and argv into a single 
argument must surely make this interpretation.)


[3]: 
https://gi.readthedocs.io/en/latest/annotations/giannotations.html#deprecated-gobject-introspection-annotations

[4]: 
https://developer.gnome.org/glib/2.60/glib-Commandline-option-parser.html#g-option-context-parse

[5]: 
https://developer.gnome.org/clutter/1.26/clutter-General.html#clutter-init

> 2]      Now, 'their' GIArgInfo definition and related question
>
>         [ you can see the complete <function> and <argument> instances for
>         [ clutter_init, as 'seen' by G-Golf here [2], but here is 'just' the first
>         [ argument, so I can ask my question>
>
> Here is the definition the argc argument, as 'seen' by G-Golf
>
>         #<<argument> 55e221b84ea0> - instance of <argument>
>           slots and values are:
>             name = argc
>             closure = -1
>             destroy = -1
>             direction = inout
>             transfert = everything
>             scope = invalid
>             type-tag = int32
>             type-desc = int32
>             is-pointer? = #f
>             may-be-null? = #f
>             is-caller-allocate? = #f
>             is-optional? = #f
>             is-return-value? = #f
>             is-skip? = #f
>             gi-argument = #<pointer 0x55e221b2cdd0>
>             gi-argument-field = v-int32
>
> So, it's definitely not a pointer, and can't be null.
> What am I missing here?

The extra level of indirection for out and inout arguments is not 
counted by [g_type_info_is_pointer][6].  (Therefore 'direction' needs to 
be known to determine the C type from the GIArgInfo data.)

[6]: 
https://developer.gnome.org/gi/1.60/gi-GITypeInfo.html#g-type-info-is-pointer

Phil

> [1]     https://www.gnu.org/software/g-golf/
>
> [2]     the clutter_init function and arguments s 'seen' by G-Golf
>
> #<<function> 55e221b5b230> - instance of <function>
>    slots and values are:
>      name = clutter-init
>      flags = ()
>      n-arg = 2
>      caller-owns = nothing
>      return-type = interface
>      type-desc = (enum clutter-init-error #<<gi-enum> 55e221a63120> 94429717812384)
>      may-return-null? = #f
>      arguments = (#<<argument> 55e221b84ea0> #<<argument> 55e221b84e10>)
>      n-gi-arg-in = 2
>      gi-args-in = #<pointer 0x55e221b2cd10>
>      n-gi-arg-out = 2
>      gi-args-out = #<pointer 0x55e221b2cce0>
>
> #<<argument> 55e221b84ea0> - instance of <argument>
>    slots and values are:
>      name = argc
>      closure = -1
>      destroy = -1
>      direction = inout
>      transfert = everything
>      scope = invalid
>      type-tag = int32
>      type-desc = int32
>      is-pointer? = #f
>      may-be-null? = #f
>      is-caller-allocate? = #f
>      is-optional? = #f
>      is-return-value? = #f
>      is-skip? = #f
>      gi-argument = #<pointer 0x55e221b2cdd0>
>      gi-argument-field = v-int32
>
> #<<argument> 55e221b84e10> - instance of <argument>
>    slots and values are:
>      name = argv
>      closure = -1
>      destroy = -1
>      direction = inout
>      transfert = everything
>      scope = invalid
>      type-tag = array
>      type-desc = (array . c)
>      is-pointer? = #t
>      may-be-null? = #t
>      is-caller-allocate? = #f
>      is-optional? = #t
>      is-return-value? = #f
>      is-skip? = #f
>      gi-argument = #<pointer 0x55e221b2cd70>
>      gi-argument-field = v-pointer