New doc format: Please continue to include annotations for ownership, types, etc...
Apologies if this isn't where this should go...
The new documentation seems a bit confusing (at least from someone used to the old format) when it comes to defining ownership transfer.
Examples:
PangoCairo->FontMap->get_default
...
Returns: PangoFontMap
...
The data is owned by the called function.
"The data is owned by the called function" - what does this even mean? It seems odd for the 'called function' to own anything. In this particular case the description clears it up - 'This object is owned by Pango and must not be freed', though this isn't always the case (see GtkSettings). Maybe the annotation should be simply 'Do not free' or 'The data is owned by the process, do not free'.
The argument will be set by the function
This should read 'The data for this argument will be set...' or simply 'This value will be set..' - the 'argument' is what the caller passed to the function, not its contents.
Transfer full/none/container/nullable stuff seemed a lot more clear to me. I know part of it is familiarity but they were also unambiguous. It would be nice to still see them in the documentation.
Thanks