Fix return transfer annotations for a number of functions and add docs

Add return transfer annotations (and while I was at it, docs), for
public functions that return MetaDisplay, MetaWindow, and MetaScreen.

http://bugzilla.gnome.org/show_bug.cgi?id=561297

http://bugzilla.gnome.org/show_bug.cgi?id=580027

src/compositor/mutter/mutter-plugin-manager.c

@@ -587,4 +587,3 @@ mutter_plugin_manager_xevent_filter (MutterPluginManager *plugin_mgr,
 
   return FALSE;
 }
-

src/compositor/mutter/mutter-plugin.c

@@ -505,6 +505,16 @@ mutter_plugin_get_xdisplay (MutterPlugin *plugin)
   return xdpy;
 }
 
+/**
+ * mutter_plugin_get_screen:
+ * @plugin: a #MutterPlugin
+ *
+ * Gets the #MetaScreen corresponding to a plugin. Each plugin instance
+ * is associated with exactly one screen; if Metacity is managing
+ * multiple screens, multiple plugin instances will be created.
+ *
+ * Return value: (transfer none): the #MetaScreen for the plugin
+ */
 MetaScreen *
 mutter_plugin_get_screen (MutterPlugin *plugin)
 {

src/core/display.c

@@ -942,6 +942,14 @@ meta_display_close (MetaDisplay *display,
   meta_quit (META_EXIT_SUCCESS);
 }
 
+/**
+ * meta_display_screen_for_root:
+ * @display: a #MetaDisplay
+ *
+ * Return the #MetaScreen corresponding to a specified X root window ID.
+ *
+ * Return Value: (transfer none): the screen for the specified root window ID, or %NULL
+ */
 MetaScreen*
 meta_display_screen_for_root (MetaDisplay *display,
                               Window       xroot)
@@ -5194,6 +5202,18 @@ meta_display_has_shape (MetaDisplay *display)
   return META_DISPLAY_HAS_SHAPE (display);
 }
 
+/**
+ * meta_display_get_focus_window:
+ * @display: a #MetaDisplay
+ *
+ * Get the window that, according to events received from X server,
+ * currently has the input focus. We may have already sent a request
+ * to the X server to move the focus window elsewhere. (The
+ * expected_focus_window records where we've last set the input
+ * focus.)
+ *
+ * Return Value: (transfer none): The current focus window
+ */
 MetaWindow *
 meta_display_get_focus_window (MetaDisplay *display)
 {

src/core/screen.c

@@ -929,6 +929,15 @@ meta_screen_composite_all_windows (MetaScreen *screen)
 #endif
 }
 
+/**
+ * meta_screen_for_x_screen:
+ * @xscreen: an X screen structure.
+ *
+ * Gets the #MetaScreen corresponding to an X screen structure.
+ *
+ * Return value: (transfer none): the #MetaScreen for the X screen
+ *   %NULL if Metacity is not managing the screen.
+ */
 MetaScreen*
 meta_screen_for_x_screen (Screen *xscreen)
 {
@@ -1089,6 +1098,18 @@ meta_screen_get_n_workspaces (MetaScreen *screen)
   return g_list_length (screen->workspaces);
 }
 
+/**
+ * meta_screen_get_workspace_by_index:
+ * @screen: a #MetaScreen
+ * @index: index of one of the screen's workspaces
+ *
+ * Gets the workspace object for one of a screen's workspaces given the workspace
+ * index. It's valid to call this function with an out-of-range index and it
+ * will robustly return %NULL.
+ *
+ * Return value: (transfer none): the workspace object with specified index, or %NULL
+ *   if the index is out of range.
+ */
 MetaWorkspace*
 meta_screen_get_workspace_by_index (MetaScreen  *screen,
                                     int          idx)
@@ -1244,6 +1265,19 @@ meta_screen_remove_workspace (MetaScreen *screen, MetaWorkspace *workspace,
   g_object_notify (G_OBJECT (screen), "n-workspaces");
 }
 
+/**
+ * meta_screen_append_new_workspace:
+ * @screen: a #MetaScreen
+ * @activate: %TRUE if the workspace should be switched to after creation
+ * @timestamp: if switching to a new workspace, timestamp to be used when
+ *   focusing a window on the new workspace. (Doesn't hurt to pass a valid
+ *   timestamp when available even if not switching workspaces.)
+ *
+ * Append a new workspace to the screen and (optionally) switch to that
+ * screen.
+ *
+ * Return value: (transfer none): the newly appended workspace.
+ */
 MetaWorkspace *
 meta_screen_append_new_workspace (MetaScreen *screen, gboolean activate,
                                   guint32 timestamp)

src/core/window.c

@@ -8610,6 +8610,14 @@ meta_window_get_rect (MetaWindow *window)
   return &window->rect;
 }
 
+/**
+ * meta_window_get_screen:
+ * @window: a #MetaWindow
+ *
+ * Gets the #MetaScreen that the window is on.
+ *
+ * Return value: (transfer none): the #MetaScreen for the window
+ */
 MetaScreen *
 meta_window_get_screen (MetaWindow *window)
 {
@@ -8640,6 +8648,16 @@ meta_window_get_window_type_atom (MetaWindow *window)
   return window->type_atom;
 }
 
+/**
+ * meta_window_get_workspace:
+ * @window: a #MetaWindow
+ *
+ * Gets the #MetaWorkspace that the window is currently displayed on.
+ * If the window is on all workspaces, returns the currently active
+ * workspace.
+ *
+ * Return value: (transfer none): the #MetaWorkspace for the window
+ */
 MetaWorkspace *
 meta_window_get_workspace (MetaWindow *window)
 {

src/core/workspace.c

@@ -1252,6 +1252,14 @@ focus_ancestor_or_mru_window (MetaWorkspace *workspace,
     }
 }
 
+/**
+ * meta_workspace_get_screen:
+ * @workspace: a #MetaWorkspace
+ *
+ * Gets the #MetaScreen that the workspace is part of.
+ *
+ * Return value: (transfer none): the #MetaScreen for the workspace
+ */
 MetaScreen *
 meta_workspace_get_screen (MetaWorkspace *workspace)
 {