Use of Return In Documentation

There seems to be a few problems or limitations with the use of the Returns: tag in our documentation.

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

2. 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.
3. 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()

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

5. No annotations for the possible values of the result

See Also

• https://www.jetbrains.com/idea/documentation/howto.html

• http://msdn.microsoft.com/en-us/library/hh916382.aspx#sectionToggle4

• https://bugzilla.gnome.org/show_bug.cgi?id=683361