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

Projects/GTK+/ReturnInDocs (last edited 2014-02-25 15:36:15 by WilliamJonMcCann)