Behaviour of getters wrt dup/ref

[Alexander Larsson <alexl redhat com>]

I got some feedback on gio about a getter function that returned a ref,
and now I'm reviewing the gio APIs for things like that, making sure its
internally consistent and consistent with gtk+/glib.

However, I'm not sure what the gtk+ standard for this is. I heard "no
reffing getters", but that is somewhat limited. Instead of theorizing,
let me take a couple of examples from gio, and see what kind of
behaviour they should have.

char *      g_app_info_get_name  (GAppInfo   *appinfo);

GAppInfo is an object with multiple implementations, like win32 and
desktop. In the current version they all return a string from the
object, but theoretically it could call some OS function to get the
result, so its nice if we dup here. 

const char * g_file_info_get_name (GFileInfo  *info);

This however always just returns whatever is in the GFileInfo. GFileInfo
is just a store for data. Do we dup this on return? That seems
unnecessary, complicating code and doing extra dups.

char *      g_drive_get_name             (GDrive            *drive);

This is unlikely to *need* a strdup, however it dups so that its
consistent with things like:

GIcon *     g_drive_get_icon             (GDrive            *drive);

This returns a ref:ed object, because we're not actually storing a GIcon
object in the GDrive object, just some string which is created at the
time get_icon is called. Is this wrong? Should I store the constructed
GIcon so that i can make a non-reffing getter?

GAppInfo *g_app_info_get_default_for_type (const char  *content_type);
GList *     g_app_info_get_all_for_type  (const char *content_type);

These aren't getters in the traditional sense, because content type is
not an object. But it has get in the name. They obviously have to
ref/dup things. But should they have a non-_get name?

char *      g_data_input_stream_get_line (GDataInputStream *data_stream,
					  gsize             *length,
					  GCancellable     *cancellable,
					  GError           **error);

This actually reads new data from the stream, so it has to dup. One
could imagine a similar call that returns some form of object instead of
a string. That would have to ref the returned value (or rather, create
it). Should it have a non _get() name? (and for consistance, should then
get_line() get_uint32() etc also have different names?)

char *      g_file_get_uri               (GFile             *file);
char *      g_file_get_parse_name        (GFile             *file);
GFile *     g_file_get_parent            (GFile             *file);

These all calculate new things, and are not traditional getters, as such
they must ref/dup. Should they be called something else?

Is it possible to have a good set of rules we can follow consistently?