Bug 578387 – Remaining API documentation additions

This adds a load of .h files to the ignore list, and documents the remaining
functions which would be useful to plugins.

It makes TOTEM_MAX_RECENT_ITEM_LEN private to totem-menu.c, since that was the
only file which used it.

It also removes a completely unused declaration of bacon_cd_selection_create
from totem-preferences.h.

See the changes to totem-sections.txt for the list of API I've considered
useful to expose (by way of documentation) to plugins.

9 files changed, 224 insertions, 14 deletions

diff --git a/src/backend/bacon-video-widget.h b/src/backend/bacon-video-widget.h
index a3b956a26..b11de921c 100644
--- a/src/backend/bacon-video-widget.h
+++ b/src/backend/bacon-video-widget.h
@@ -292,6 +292,7 @@ void bacon_video_widget_get_metadata		 (BaconVideoWidget *bvw,
  * @VISUAL_NORMAL: normal size (320×25)
  * @VISUAL_LARGE: large size (480×25)
  * @VISUAL_EXTRA_LARGE: extra large size (600×30)
+ * @NUM_VISUAL_QUALITIES: the number of visual qualities available
  *
  * The different visualisation sizes or qualities available for use
  * with bacon_video_widget_set_visuals_quality().
diff --git a/src/plugins/totem-plugin.h b/src/plugins/totem-plugin.h
index 85e8c7a2a..840213c0c 100644
--- a/src/plugins/totem-plugin.h
+++ b/src/plugins/totem-plugin.h
@@ -55,9 +55,49 @@ typedef struct {
 	GObject parent;
 } TotemPlugin;
 
+/**
+ * TotemPluginActivationFunc:
+ * @plugin: the #TotemPlugin
+ * @totem: a #TotemObject
+ * @error: a #GError
+ *
+ * Called when the user has requested @plugin be activated, this function should be used to initialise
+ * any resources the plugin needs, and attach itself to the Totem UI.
+ *
+ * If an error is encountered while setting up the plugin, @error should be set, and the function
+ * should return %FALSE. Totem will then not mark the plugin as activated, and will ensure it's not loaded
+ * again unless explicitly asked for by the user.
+ *
+ * Return value: %TRUE on success, %FALSE otherwise
+ **/
 typedef gboolean	(*TotemPluginActivationFunc)		(TotemPlugin *plugin, TotemObject *totem,
 								 GError **error);
+
+/**
+ * TotemPluginDeactivationFunc:
+ * @plugin: the #TotemPlugin
+ * @totem: a #TotemObject
+ *
+ * Called when the user has requested @plugin be deactivated, this function should destroy all resources
+ * created during the plugin's lifetime, especially those created in the activation function.
+ *
+ * It should be possible to activate and deactivate the plugin multiple times sequentially in a single Totem
+ * session without memory or resource leaks, or errors.
+ **/
 typedef void		(*TotemPluginDeactivationFunc)		(TotemPlugin *plugin, TotemObject *totem);
+
+/**
+ * TotemPluginWidgetFunc:
+ * @plugin: the #TotemPlugin
+ *
+ * Called when the configuration dialogue for the plugin needs to be built, this function should return
+ * a complete window which will be shown by the Totem code. The widget needs to be capable of hiding itself
+ * when configuration is complete.
+ *
+ * If your plugin is not configurable, do not define this function.
+ *
+ * Return value: a #GtkWidget
+ **/
 typedef GtkWidget *	(*TotemPluginWidgetFunc)		(TotemPlugin *plugin);
 typedef gboolean	(*TotemPluginBooleanFunc)		(TotemPlugin *plugin);
 
@@ -133,15 +173,33 @@ GtkBuilder *     totem_plugin_load_interface    (TotemPlugin *plugin,
 
 GList *          totem_get_plugin_paths            (void);
 
-/*
- * Utility macro used to register plugins
+/**
+ * TOTEM_PLUGIN_REGISTER:
+ * @PluginName: the plugin's name in camelcase
+ * @plugin_name: the plugin's name in lowercase, with underscores
  *
- * use: TOTEM_PLUGIN_REGISTER(TOTEMSamplePlugin, totem_sample_plugin)
- */
-
+ * Registers a new Totem plugin type. A plugin is, at its core, just a class which is
+ * instantiated and activated on the user's request. This macro registers that class.
+ **/
 #define TOTEM_PLUGIN_REGISTER(PluginName, plugin_name)				\
 	TOTEM_PLUGIN_REGISTER_EXTENDED(PluginName, plugin_name, {})
 
+/**
+ * TOTEM_PLUGIN_REGISTER_EXTENDED:
+ * @PluginName: the plugin's name in camelcase
+ * @plugin_name: the plugin's name in lowercase, with underscores
+ * @_C_: extra code to call in the module type registration function
+ *
+ * Registers a new Totem plugin type with custom code in the module type registration
+ * function. See TOTEM_PLUGIN_REGISTER() for more information about the registration
+ * process.
+ *
+ * A variable named @our_info is available with the module's #GTypeInfo information.
+ * @plugin_module_type is the plugin's #GTypeModule.
+ * @<replaceable>plugin_name</replaceable>_type is the plugin's newly-registered #GType
+ * (where <replaceable>plugin_name</replaceable> is the plugin name passed to the
+ * TOTEM_PLUGIN_REGISTER_EXTENDED() macro).
+ **/
 #define TOTEM_PLUGIN_REGISTER_EXTENDED(PluginName, plugin_name, _C_)		\
 	_TOTEM_PLUGIN_REGISTER_EXTENDED_BEGIN (PluginName, plugin_name) {_C_;} _TOTEM_PLUGIN_REGISTER_EXTENDED_END(plugin_name)
 
@@ -200,9 +258,25 @@ register_totem_plugin (GTypeModule *module)					\
 	return plugin_name##_type;						\
 }
 
+/**
+ * TOTEM_PLUGIN_REGISTER_TYPE:
+ * @type_name: the type's name in lowercase, with underscores
+ *
+ * Calls the type registration function for a type inside a plugin module previously
+ * defined with TOTEM_PLUGIN_DEFINE_TYPE().
+ **/
 #define TOTEM_PLUGIN_REGISTER_TYPE(type_name)					\
 	type_name##_register_type (plugin_module_type)
 
+/**
+ * TOTEM_PLUGIN_DEFINE_TYPE:
+ * @TypeName: the type name in camelcase
+ * @type_name: the type name in lowercase, with underscores
+ * @TYPE_PARENT: the type's parent name in uppercase, with underscores
+ *
+ * Registers a type to be used inside a Totem plugin, but not the plugin's itself;
+ * use TOTEM_PLUGIN_REGISTER() for that.
+ **/
 #define TOTEM_PLUGIN_DEFINE_TYPE(TypeName, type_name, TYPE_PARENT)		\
 static void type_name##_init (TypeName *self); 					\
 static void type_name##_class_init (TypeName##Class *klass); 			\
diff --git a/src/totem-interface.c b/src/totem-interface.c
index 3bf662c61..6c4ddd8df 100644
--- a/src/totem-interface.c
+++ b/src/totem-interface.c
@@ -78,6 +78,15 @@ totem_interface_error_dialog (const char *title, const char *reason,
 	return error_dialog;
 }
 
+/**
+ * totem_interface_error:
+ * @title: the error title
+ * @reason: the error reason (secondary text)
+ * @parent: the error dialogue's parent #GtkWindow
+ *
+ * Display a modal error dialogue with @title as its primary error text, and @reason
+ * as its secondary text.
+ **/
 void
 totem_interface_error (const char *title, const char *reason,
 		GtkWindow *parent)
@@ -92,6 +101,15 @@ totem_interface_error (const char *title, const char *reason,
 	gtk_window_present (GTK_WINDOW (error_dialog));
 }
 
+/**
+ * totem_interface_error_blocking:
+ * @title: the error title
+ * @reason: the error reason (secondary text)
+ * @parent: the error dialogue's parent #GtkWindow
+ *
+ * Display a modal error dialogue like totem_interface_error() which blocks until the user has
+ * dismissed it.
+ **/
 void
 totem_interface_error_blocking (const char *title, const char *reason,
 		GtkWindow *parent)
@@ -147,7 +165,7 @@ link_button_clicked_cb (GtkWidget *widget, Totem *totem)
  * @parent: the error dialogue's parent #GtkWindow
  * @totem: a #TotemObject
  *
- * Display a modal error dialogue like totem_interface_error_dialog(),
+ * Display a modal error dialogue like totem_interface_error(),
  * but add a button which will open @uri in a browser window.
  **/
 void
@@ -354,6 +372,18 @@ totem_interface_get_license (void)
 			  NULL);
 }
 
+/**
+ * totem_interface_boldify_label:
+ * @builder: a #GtkBuilder
+ * @name: the label name
+ *
+ * Makes the text of the @name label bold.
+ *
+ * This should be used instead of putting the Pango markup directly into a #GtkBuilder
+ * UI file so that translators don't have to translate text formatting markup unnecessarily.
+ *
+ * This function can only be used if the entire text of a label is to be made bold.
+ **/
 void
 totem_interface_boldify_label (GtkBuilder *builder, const char *name)
 {
@@ -388,6 +418,18 @@ totem_interface_boldify_label (GtkBuilder *builder, const char *name)
 	g_free (str_final);
 }
 
+/**
+ * totem_interface_italicise_label:
+ * @builder: a #GtkBuilder
+ * @name: the label name
+ *
+ * Makes the text of the @name label italic.
+ *
+ * This should be used instead of putting the Pango markup directly into a #GtkBuilder
+ * UI file so that translators don't have to translate text formatting markup unnecessarily.
+ *
+ * This function can only be used if the entire text of a label is to be made italic.
+ **/
 void
 totem_interface_italicise_label (GtkBuilder *builder, const char *name)
 {
diff --git a/src/totem-interface.h b/src/totem-interface.h
index cfd3b747f..d10128a68 100644
--- a/src/totem-interface.h
+++ b/src/totem-interface.h
@@ -53,10 +53,10 @@ void		 totem_interface_error_with_link (const char *title,
 void		 totem_interface_set_transient_for (GtkWindow *window,
 						    GtkWindow *parent);
 char *		 totem_interface_get_license	(void);
-void		 totem_interface_boldify_label	(GtkBuilder *xml,
-						 const char *label);
-void		 totem_interface_italicise_label(GtkBuilder *xml,
-						 const char *label);
+void		 totem_interface_boldify_label	(GtkBuilder *builder,
+						 const char *name);
+void		 totem_interface_italicise_label(GtkBuilder *builder,
+						 const char *name);
 
 G_END_DECLS
 
diff --git a/src/totem-menu.c b/src/totem-menu.c
index 6e4d5050a..4ae4f7cab 100644
--- a/src/totem-menu.c
+++ b/src/totem-menu.c
@@ -36,6 +36,8 @@
 
 #include "debug.h"
 
+#define TOTEM_MAX_RECENT_ITEM_LEN 40
+
 /* Callback functions for GtkBuilder */
 G_MODULE_EXPORT void open_action_callback (GtkAction *action, Totem *totem);
 G_MODULE_EXPORT void open_location_action_callback (GtkAction *action, Totem *totem);
diff --git a/src/totem-menu.h b/src/totem-menu.h
index 417a22033..8d9a46e9a 100644
--- a/src/totem-menu.h
+++ b/src/totem-menu.h
@@ -27,8 +27,6 @@
 
 G_BEGIN_DECLS
 
-#define TOTEM_MAX_RECENT_ITEM_LEN 40
-
 void totem_ui_manager_setup (Totem *totem);
 
 void totem_sublang_update (Totem *totem);
diff --git a/src/totem-object.c b/src/totem-object.c
index c38647e9d..04caa5596 100644
--- a/src/totem-object.c
+++ b/src/totem-object.c
@@ -491,6 +491,14 @@ totem_get_current_mrl (Totem *totem)
 	return totem_playlist_get_current_mrl (totem->playlist, NULL);
 }
 
+/**
+ * totem_get_playlist_length:
+ * @totem: a #TotemObject
+ *
+ * Returns the length of the current playlist.
+ *
+ * Return value: the playlist length
+ **/
 guint
 totem_get_playlist_length (Totem *totem)
 {
@@ -502,18 +510,44 @@ totem_get_playlist_length (Totem *totem)
 	return last + 1;
 }
 
+/**
+ * totem_get_playlist_pos:
+ * @totem: a #TotemObject
+ *
+ * Returns the %0-based index of the current entry in the playlist. If
+ * there is no current entry in the playlist, %-1 is returned.
+ *
+ * Return value: the index of the current playlist entry, or %-1
+ **/
 int
 totem_get_playlist_pos (Totem *totem)
 {
 	return totem_playlist_get_current (totem->playlist);
 }
 
+/**
+ * totem_get_title_at_playlist_pos:
+ * @totem: a #TotemObject
+ * @index: the %0-based entry index
+ *
+ * Gets the title of the playlist entry at @index.
+ *
+ * Return value: the entry title at @index, or %NULL; free with g_free()
+ **/
 char *
 totem_get_title_at_playlist_pos (Totem *totem, guint index)
 {
 	return totem_playlist_get_title (totem->playlist, index);
 }
 
+/**
+ * totem_get_short_title:
+ * @totem: a #TotemObject
+ *
+ * Gets the title of the current entry in the playlist.
+ *
+ * Return value: the current entry's title, or %NULL; free with g_free()
+ **/
 char *
 totem_get_short_title (Totem *totem)
 {
@@ -2797,6 +2831,13 @@ totem_action_toggle_controls (Totem *totem)
  	gtk_toggle_action_set_active (GTK_TOGGLE_ACTION (action), !state);
 }
 
+/**
+ * totem_action_next_angle:
+ * @totem: a #TotemObject
+ *
+ * Switches to the next angle, if watching a DVD. If not watching a DVD, this is a
+ * no-op.
+ **/
 void
 totem_action_next_angle (Totem *totem)
 {
@@ -2804,6 +2845,17 @@ totem_action_next_angle (Totem *totem)
 		bacon_video_widget_dvd_event (totem->bvw, BVW_DVD_NEXT_ANGLE);
 }
 
+/**
+ * totem_action_set_playlist_index:
+ * @totem: a #TotemObject
+ * @index: the new playlist index
+ *
+ * Sets the %0-based playlist index to @index, causing Totem to load and
+ * start playing that playlist entry.
+ *
+ * If @index is higher than the current length of the playlist, this
+ * has the effect of restarting the current playlist entry.
+ **/
 void
 totem_action_set_playlist_index (Totem *totem, guint index)
 {
@@ -2996,6 +3048,14 @@ totem_action_remote (Totem *totem, TotemRemoteCommand cmd, const char *url)
 	}
 }
 
+/**
+ * totem_action_remote_set_setting:
+ * @totem: a #TotemObject
+ * @setting: a #TotemRemoteSetting
+ * @value: the new value for the setting
+ *
+ * Sets @setting to @value on this instance of Totem.
+ **/
 void totem_action_remote_set_setting (Totem *totem,
 				      TotemRemoteSetting setting,
 				      gboolean value)
@@ -3018,6 +3078,15 @@ void totem_action_remote_set_setting (Totem *totem,
 	gtk_toggle_action_set_active (GTK_TOGGLE_ACTION (action), value);
 }
 
+/**
+ * totem_action_remote_get_setting:
+ * @totem: a #TotemObject
+ * @setting: a #TotemRemoteSetting
+ *
+ * Returns the value of @setting for this instance of Totem.
+ *
+ * Return value: %TRUE if the setting is enabled, %FALSE otherwise
+ **/
 gboolean totem_action_remote_get_setting (Totem *totem,
 					  TotemRemoteSetting setting)
 {
@@ -3167,6 +3236,14 @@ totem_is_playing (Totem *totem)
 	return bacon_video_widget_is_playing (totem->bvw) != FALSE;
 }
 
+/**
+ * totem_is_paused:
+ * @totem: a #TotemObject
+ *
+ * Returns %TRUE if playback is paused.
+ *
+ * Return value: %TRUE if playback is paused, %FALSE otherwise
+ **/
 gboolean
 totem_is_paused (Totem *totem)
 {
diff --git a/src/totem-preferences.h b/src/totem-preferences.h
index fefa3ee25..0f3f6b198 100644
--- a/src/totem-preferences.h
+++ b/src/totem-preferences.h
@@ -34,8 +34,6 @@ G_BEGIN_DECLS
 void totem_setup_preferences (Totem *totem);
 void totem_preferences_visuals_setup (Totem *totem);
 
-GtkWidget * bacon_cd_selection_create (void);
-
 G_END_DECLS
 
 #endif /* TOTEM_PREFERENCES_H */
diff --git a/src/totem.h b/src/totem.h
index 25b6e12f7..89f27fb25 100644
--- a/src/totem.h
+++ b/src/totem.h
@@ -33,6 +33,11 @@
 #include <totem-disc.h>
 #include "totem-playlist.h"
 
+/**
+ * TOTEM_GCONF_PREFIX:
+ *
+ * The GConf prefix under which all Totem GConf keys are stored.
+ **/
 #define TOTEM_GCONF_PREFIX "/apps/totem"
 
 G_BEGIN_DECLS
@@ -103,6 +108,13 @@ typedef enum {
 	TOTEM_REMOTE_COMMAND_TOGGLE_ASPECT
 } TotemRemoteCommand;
 
+/**
+ * TotemRemoteSetting:
+ * @TOTEM_REMOTE_SETTING_SHUFFLE: whether shuffle is enabled
+ * @TOTEM_REMOTE_SETTING_REPEAT: whether repeat is enabled
+ *
+ * Represents a boolean setting or preference on a remote Totem instance.
+ **/
 typedef enum {
 	TOTEM_REMOTE_SETTING_SHUFFLE,
 	TOTEM_REMOTE_SETTING_REPEAT
@@ -125,6 +137,12 @@ GQuark totem_disc_media_type_quark	(void);
 #define TOTEM_IS_OBJECT_CLASS(klass)   (G_CHECK_INSTANCE_GET_CLASS ((klass), totem_object_get_type ()))
 
 /**
+ * Totem:
+ *
+ * The #Totem object is a handy synonym for #TotemObject, and the two can be used interchangably.
+ **/
+
+/**
  * TotemObject:
  *
  * All the fields in the #TotemObject structure are private and should never be accessed directly.