introspection: Build with --warn-all --warn-error

* Use --warn-all, --warn-error
* Fix various broken gtk-doc
* Drop unused shell_get_event_related
* For header defines, we currently require them to end in _H to be skipped
* Drop the no-longer-necessary fix-meta-rectangle.py hack
* Move to the convention of using -private.h for headers that are,
  well, private.
* Add shell-wm-private.h

src/Makefile.am

@@ -80,20 +80,17 @@ shell_public_headers_h =		\
 	shell-wm.h              \
 	shell-xfixes-cursor.h
 
-# Files we don't want to be scanned by introspection
-non_gir_sources =				\
-	shell-embedded-window-private.h		\
-	shell-global-private.h			\
-	shell-window-tracker-private.h
-
 libgnome_shell_la_SOURCES =		\
 	$(shell_built_sources)		\
 	$(shell_public_headers_h)	\
-	$(non_gir_sources)		\
+	shell-app-private.h		\
+	shell-embedded-window-private.h	\
+	shell-global-private.h		\
+	shell-window-tracker-private.h	\
+	shell-wm-private.h	\
 	gnome-shell-plugin.c		\
 	gtk-compat.h			\
 	shell-app.c			\
-	shell-app-private.h		\
 	shell-app-system.c		\
 	shell-app-usage.c		\
 	shell-arrow.c			\
@@ -113,6 +110,9 @@ libgnome_shell_la_SOURCES =		\
 	shell-wm.c              \
 	shell-xfixes-cursor.c
 
+libgnome_shell_la_gir_sources = \
+	$(filter-out %-private.h $(shell_recorder_non_gir_sources), $(shell_public_headers_h) $(libgnome_shell_la_SOURCES))
+
 shell_recorder_sources =        \
 	shell-recorder.c	\
 	shell-recorder.h
@@ -123,8 +123,7 @@ shell_recorder_non_gir_sources =  \
 	shell-recorder-src.h
 
 if BUILD_RECORDER
-libgnome_shell_la_SOURCES += $(shell_recorder_sources)
+libgnome_shell_la_SOURCES += $(shell_recorder_sources) $(shell_recorder_non_gir_sources)
-non_gir_sources += $(shell_recorder_non_gir_sources)
 
 noinst_PROGRAMS += test-recorder
 
@@ -136,8 +135,6 @@ test_recorder_SOURCES =     \
 	test-recorder.c
 endif BUILD_RECORDER
 
-libgnome_shell_la_gir_sources = \
-	$(filter-out $(non_gir_sources), $(libgnome_shell_la_SOURCES))
 
 shell-marshal.h: stamp-shell-marshal.h
 	@true
@@ -199,6 +196,8 @@ Shell-0.1.gir: $(mutter) $(G_IR_SCANNER) St-1.0.gir libgnome-shell.la Makefile
 	$(AM_V_GEN) $(G_IR_SCANNER)			\
 		--namespace=Shell			\
 		--nsversion=0.1				\
+		--warn-all				\
+		--warn-error				\
 		--add-include-path=$(MUTTER_LIB_DIR)/mutter/ \
 		--include=Clutter-1.0			\
 		--include=Meta-2.31			\
@@ -210,10 +209,7 @@ Shell-0.1.gir: $(mutter) $(G_IR_SCANNER) St-1.0.gir libgnome-shell.la Makefile
 		$(addprefix $(srcdir)/,$(libgnome_shell_la_gir_sources)) \
 		$(libgnome_shell_la_CPPFLAGS)		\
 		-I $(srcdir)				\
-		-o $@.tmp &&				\
+		-o $@
-	$(PYTHON) $(srcdir)/fix-meta-rectangle.py $@.tmp $@.tmp2 &&	\
-	rm $@.tmp &&							\
-	mv $@.tmp2 $@
 CLEANFILES += Shell-0.1.gir
 EXTRA_DIST += fix-meta-rectangle.py
 
@@ -231,13 +227,15 @@ St-1.0.gir: $(mutter) $(G_IR_SCANNER) libst-1.0.la Makefile
 	$(AM_V_GEN) $(G_IR_SCANNER)						\
 	        --namespace=St							\
 	        --nsversion=1.0							\
+		--warn-all							\
+		--warn-error							\
 	        --include=Clutter-1.0						\
 	        --include=Gtk-3.0						\
 		--add-include-path=$(builddir)     				\
 	        --libtool="$(LIBTOOL)"						\
 	        --library=libst-1.0.la						\
 	        -DST_COMPILATION						\
-	        $(addprefix $(srcdir)/,$(st_source_h))				\
+	        $(filter-out %-private.h, $(addprefix $(srcdir)/,$(st_source_h))) \
 	        $(addprefix $(srcdir)/,$(st_source_c))				\
 	        $(srcdir)/st-enum-types.h					\
 	        $(st_cflags)							\
@@ -254,11 +252,13 @@ Gdm-1.0.gir: $(mutter) $(G_IR_SCANNER) libgdmuser-1.0.la Makefile
 	$(AM_V_GEN) $(G_IR_SCANNER)			\
 		--namespace=Gdm				\
 		--nsversion=1.0				\
+		--warn-all				\
+		--warn-error				\
 		--include=GObject-2.0			\
 		--include=GdkPixbuf-2.0			\
 		--libtool="$(LIBTOOL)"			\
 		--library=libgdmuser-1.0.la		\
-		$(addprefix $(srcdir)/,$(gdmuser_source_h))	\
+		$(filter-out %-private.h, $(addprefix $(srcdir)/,$(gdmuser_source_h)))	\
 		$(addprefix $(srcdir)/,$(gdmuser_source_c))	\
 		$(gdmuser_cflags)				\
 		-o $@

src/gdmuser/gdm-user-manager.c

@@ -963,14 +963,14 @@ get_seat_proxy (GdmUserManager *manager)
 }
 
 /**
- * gdm_manager_get_user:
+ * gdm_user_manager_get_user:
  * @manager: the manager to query.
  * @username: the login name of the user to get.
  *
  * Retrieves a pointer to the #GdmUser object for the login named @username
  * from @manager. This pointer is not a reference, and should not be released.
  *
- * Returns: a pointer to a #GdmUser object.
+ * Returns: (transfer none): a pointer to a #GdmUser object.
  **/
 GdmUser *
 gdm_user_manager_get_user (GdmUserManager *manager,
@@ -996,6 +996,17 @@ gdm_user_manager_get_user (GdmUserManager *manager,
         return user;
 }
 
+
+/**
+ * gdm_user_manager_get_user_by_uid:
+ * @manager: the manager to query.
+ * @uid: the user id
+ *
+ * Retrieves a pointer to the #GdmUser object for the login named @username
+ * from @manager.
+ *
+ * Returns: (transfer none): a pointer to a #GdmUser object.
+ **/
 GdmUser *
 gdm_user_manager_get_user_by_uid (GdmUserManager *manager,
                                   gulong          uid)
@@ -1658,6 +1669,11 @@ gdm_user_manager_finalize (GObject *object)
         G_OBJECT_CLASS (gdm_user_manager_parent_class)->finalize (object);
 }
 
+/**
+ * gdm_user_manager_ref_default:
+ *
+ * Returns: (transfer full): The singleton #GdmUserManager object.
+ */
 GdmUserManager *
 gdm_user_manager_ref_default (void)
 {

src/gdmuser/gdm-user-private.h

@@ -21,8 +21,8 @@
  * Private interfaces to the GdmUser object
  */
 
-#ifndef __GDM_USER_PRIVATE__
+#ifndef __GDM_USER_PRIVATE_H
-#define __GDM_USER_PRIVATE__ 1
+#define __GDM_USER_PRIVATE_H
 
 #include <pwd.h>
 
@@ -41,4 +41,4 @@ void _gdm_user_icon_changed     (GdmUser             *user);
 
 G_END_DECLS
 
-#endif /* !__GDM_USER_PRIVATE__ */
+#endif /* !__GDM_USER_PRIVATE_H */

src/gdmuser/gdm-user.c

@@ -78,13 +78,13 @@ struct _GdmUser {
         GFileMonitor   *icon_monitor;
 };
 
-typedef struct _GdmUserClass
+struct _GdmUserClass
 {
         GObjectClass parent_class;
 
         void (* icon_changed)     (GdmUser *user);
         void (* sessions_changed) (GdmUser *user);
-} GdmUserClass;
+};
 
 static void gdm_user_finalize     (GObject      *object);
 
@@ -150,6 +150,12 @@ gdm_user_get_num_sessions (GdmUser    *user)
         return g_list_length (user->sessions);
 }
 
+/**
+ * gdm_user_get_sessions:
+ * @user: a #GdmUser
+ *
+ * Returns: (transfer none) (element-type utf8): Session identifier strings
+ */
 GList *
 gdm_user_get_sessions (GdmUser *user)
 {
@@ -1103,6 +1109,13 @@ frame_pixbuf (GdkPixbuf *source)
         return dest;
 }
 
+/**
+ * gdm_user_render_icon:
+ * @user: a #GdmUser:
+ * @icon_size: icon size in pixels
+ *
+ * Returns: (transfer full): A new icon for the user
+ */
 GdkPixbuf *
 gdm_user_render_icon (GdmUser   *user,
                       gint       icon_size)

src/gdmuser/gdm-user.h

@@ -22,8 +22,8 @@
  * Facade object for user data, owned by GdmUserManager
  */
 
-#ifndef __GDM_USER__
+#ifndef __GDM_USER_H
-#define __GDM_USER__ 1
+#define __GDM_USER_H
 
 #include <sys/types.h>
 #include <gtk/gtk.h>
@@ -36,6 +36,7 @@ G_BEGIN_DECLS
 #define GDM_IS_USER(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), GDM_TYPE_USER))
 
 typedef struct _GdmUser GdmUser;
+typedef struct _GdmUserClass GdmUserClass;
 
 GType                 gdm_user_get_type            (void) G_GNUC_CONST;
 

src/gnome-shell-plugin.c

@@ -51,7 +51,7 @@
 
 #include "shell-global-private.h"
 #include "shell-perf-log.h"
-#include "shell-wm.h"
+#include "shell-wm-private.h"
 #include "st.h"
 
 static void gnome_shell_plugin_dispose     (GObject *object);

src/shell-app-system.c

@@ -1282,8 +1282,8 @@ shell_app_info_create_icon_texture (ShellAppInfo *info, float size)
  * shell_app_info_get_source_window:
  * @info: A #ShellAppInfo
  *
- * If @info is tracking a #MetaWindow, return that window.
+ * Returns: (transfer none): If @info is tracking a #MetaWindow,
- * Otherwise, return %NULL.
+ *   return that window.  Otherwise, return %NULL.
  */
 MetaWindow *
 shell_app_info_get_source_window (ShellAppInfo *info)

src/shell-global.c

@@ -511,7 +511,7 @@ shell_global_get_gdk_screen (ShellGlobal *global)
  *
  * Gets the list of MutterWindows for the plugin's screen
  *
- * Return value: (element-type MutterWindow) (transfer none): the list of windows
+ * Return value: (element-type Meta.MutterWindow) (transfer none): the list of windows
  */
 GList *
 shell_global_get_windows (ShellGlobal *global)
@@ -1369,7 +1369,7 @@ shell_get_event_state (ClutterEvent *event)
  *
  * Get the global GSettings instance.
  *
- * Return value: (transfer none) The GSettings object (transfer none).
+ * Return value: (transfer none): The GSettings object
  */
 GSettings *
 shell_global_get_settings (ShellGlobal *global)
@@ -1467,13 +1467,13 @@ shell_global_get_current_time (ShellGlobal *global)
 }
 
 /**
- * shell_global_get_app_launch_context:
+ * shell_global_create_app_launch_context:
  * @global: A #ShellGlobal
  *
  * Create a #GAppLaunchContext set up with the correct timestamp, and
  * targeted to activate on the current workspace.
  *
- * Return value: A new #GAppLaunchContext
+ * Return value: (transfer full): A new #GAppLaunchContext
  */
 GAppLaunchContext *
 shell_global_create_app_launch_context (ShellGlobal *global)

src/shell-global.h

@@ -32,8 +32,6 @@ GType            shell_global_get_type            (void) G_GNUC_CONST;
 gboolean shell_clutter_texture_set_from_pixbuf (ClutterTexture *texture,
                                                 GdkPixbuf      *pixbuf);
 
-ClutterActor *shell_get_event_related(ClutterEvent *event);
-
 ShellGlobal *shell_global_get (void);
 
 MetaScreen *shell_global_get_screen (ShellGlobal  *global);

src/shell-perf-log.c

@@ -686,7 +686,7 @@ shell_perf_log_collect_statistics (ShellPerfLog *perf_log)
 /**
  * shell_perf_log_replay:
  * @perf_log: a #ShellPerfLog
- * @replay_function: function to call for each event in the log
+ * @replay_function: (scope call): function to call for each event in the log
  * @user_data: data to pass to @replay_function
  *
  * Replays the log by calling the given function for each event

src/shell-window-tracker.c

@@ -715,7 +715,7 @@ shell_window_tracker_finalize (GObject *object)
 }
 
 /**
- * shell_window_tracker_get_window_app
+ * shell_window_tracker_get_window_app:
  * @monitor: An app monitor instance
  * @metawin: A #MetaWindow
  *
@@ -741,7 +741,7 @@ shell_window_tracker_get_window_app (ShellWindowTracker *monitor,
 
 
 /**
- * shell_app_system_get_from_pid:
+ * shell_window_tracker_get_app_from_pid:
  * @self; A #ShellAppSystem
  * @pid: A Unix process identifier
  *

src/shell-wm-private.h

@@ -0,0 +1,40 @@
+/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
+#ifndef __SHELL_WM_PRIVATE_H__
+#define __SHELL_WM_PRIVATE_H__
+
+#include "shell-wm.h"
+
+G_BEGIN_DECLS
+
+/* These forward along the different effects from GnomeShellPlugin */
+
+void _shell_wm_minimize   (ShellWM      *wm,
+			   MutterWindow *actor);
+void _shell_wm_maximize   (ShellWM      *wm,
+			   MutterWindow *actor,
+			   gint          x,
+			   gint          y,
+			   gint          width,
+			   gint          height);
+void _shell_wm_unmaximize (ShellWM      *wm,
+			   MutterWindow *actor,
+			   gint          x,
+			   gint          y,
+			   gint          width,
+			   gint          height);
+void _shell_wm_map        (ShellWM      *wm,
+			   MutterWindow *actor);
+void _shell_wm_destroy    (ShellWM      *wm,
+			   MutterWindow *actor);
+
+void _shell_wm_switch_workspace (ShellWM              *wm,
+				 gint                  from,
+				 gint                  to,
+				 MetaMotionDirection   direction);
+void _shell_wm_kill_window_effects  (ShellWM              *wm,
+				     MutterWindow         *actor);
+void _shell_wm_kill_switch_workspace (ShellWM              *wm);
+
+G_END_DECLS
+
+#endif /* __SHELL_WM_PRIVATE_H__ */

src/shell-wm.c

@@ -4,7 +4,7 @@
 
 #include <string.h>
 
-#include "shell-wm.h"
+#include "shell-wm-private.h"
 #include "shell-global.h"
 #include "shell-marshal.h"
 

src/shell-wm.h

@@ -27,8 +27,6 @@ GType    shell_wm_get_type                    (void) G_GNUC_CONST;
 
 ShellWM *shell_wm_new                         (MutterPlugin *plugin);
 
-GList   *shell_wm_get_switch_workspace_actors (ShellWM      *wm);
-
 void     shell_wm_completed_minimize          (ShellWM      *wm,
                                                MutterWindow *actor);
 void     shell_wm_completed_maximize          (ShellWM      *wm,
@@ -41,36 +39,6 @@ void     shell_wm_completed_destroy           (ShellWM      *wm,
                                                MutterWindow *actor);
 void     shell_wm_completed_switch_workspace  (ShellWM      *wm);
 
-
-/* These forward along the different effects from GnomeShellPlugin */
-
-void _shell_wm_minimize   (ShellWM      *wm,
-			   MutterWindow *actor);
-void _shell_wm_maximize   (ShellWM      *wm,
-			   MutterWindow *actor,
-			   gint          x,
-			   gint          y,
-			   gint          width,
-			   gint          height);
-void _shell_wm_unmaximize (ShellWM      *wm,
-			   MutterWindow *actor,
-			   gint          x,
-			   gint          y,
-			   gint          width,
-			   gint          height);
-void _shell_wm_map        (ShellWM      *wm,
-			   MutterWindow *actor);
-void _shell_wm_destroy    (ShellWM      *wm,
-			   MutterWindow *actor);
-
-void _shell_wm_switch_workspace (ShellWM              *wm,
-				 gint                  from,
-				 gint                  to,
-				 MetaMotionDirection   direction);
-void _shell_wm_kill_window_effects  (ShellWM              *wm,
-				     MutterWindow         *actor);
-void _shell_wm_kill_switch_workspace (ShellWM              *wm);
-
 /* Keybinding stuff */
 void shell_wm_takeover_keybinding (ShellWM    *wm,
 				   const char *binding_name);

src/st/st-clipboard.c

@@ -305,7 +305,7 @@ st_clipboard_get_default (void)
 /**
  * st_clipboard_get_text:
  * @clipboard: A #StCliboard
- * @callback: function to be called when the text is retreived
+ * @callback: (scope async): function to be called when the text is retreived
  * @user_data: data to be passed to the callback
  *
  * Request the data from the clipboard in text form. @callback is executed

src/st/st-container.c

@@ -168,7 +168,7 @@ st_container_move_child (StContainer  *container,
  * Get the internal list of @container's child actors. This function
  * should only be used by subclasses of StContainer
  *
- * Returns: list of @container's child actors
+ * Returns: (element-type Clutter.Actor) (transfer none): list of @container's child actors
  */
 GList *
 st_container_get_children_list (StContainer *container)

src/st/st-texture-cache.c

@@ -831,7 +831,7 @@ st_texture_cache_bind_pixbuf_property (StTextureCache    *cache,
 }
 
 /**
- * st_texture_cache_load:
+ * st_texture_cache_load: (skip)
  * @cache: A #StTextureCache
  * @key: Arbitrary string used to refer to item
  * @policy: Caching policy
@@ -1272,6 +1272,8 @@ st_texture_cache_load_uri_sync (StTextureCache *cache,
  * This function synchronously loads the given file path
  * into a COGL texture.  On error, a warning is emitted
  * and %COGL_INVALID_HANDLE is returned.
+ *
+ * Returns: (transfer full): a new #CoglHandle
  */
 CoglHandle
 st_texture_cache_load_file_to_cogl_texture (StTextureCache *cache,

src/st/st-texture-cache.h

@@ -107,6 +107,17 @@ ClutterActor *st_texture_cache_load_from_raw  (StTextureCache    *cache,
                                                int                size,
                                                GError           **error);
 
+/**
+ * StTextureCacheLoader: (skip)
+ * @cache: a #StTextureCache
+ * @key: Unique identifier for this texture
+ * @data: Callback user data
+ * @error: A #GError
+ *
+ * See st_texture_cache_load().  Implementations should return a
+ * texture handle for the given key, or set @error.
+ *
+ */
 typedef CoglHandle (*StTextureCacheLoader) (StTextureCache *cache, const char *key, void *data, GError **error);
 
 CoglHandle st_texture_cache_load (StTextureCache       *cache,