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/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)
 {