Use of Return In Documentation
There seems to be a few problems or limitations with the use of the Returns: tag in our documentation.
- Inconsistent use of transfer annotations
- I think we should endeavor to have only explicit annotations. Implicit ones are just confusing. Especially since there are so many special cases.
No annotation for whether a NULL return is possible or impossible (bug #660879 and bug 626395)
- Have such a thing could be useful for IDEs to provide hints about whether you need to check for null when you use a function.
- Text descriptions of how to release the value after use that assume the use of the C language
* Returns: (transfer full): a %NULL-terminated array of strings, * free with g_strfreev() when done
* Returns: a newly allocated #GtkBorder-struct. Free with gtk_border_free()
- Text descriptions of transfer none
* Returns: the menu’s title in tearoff mode. This is an internal copy of the * string which must not be freed.
- No annotations for the possible values of the result