[gtk-doc] Document GrlPluginRegistry

2 files changed, 205 insertions, 2 deletions

diff --git a/src/grl-plugin-registry.c b/src/grl-plugin-registry.c
index b95b1dc..e16ed19 100644
--- a/src/grl-plugin-registry.c
+++ b/src/grl-plugin-registry.c
@@ -20,6 +20,23 @@
  *
  */
 
+/**
+ * SECTION:grl-plugin-registry
+ * @short_description: Grilo plugins loader and manager
+ * @see_also: #GrlMediaPlugin, #GrlMetadataSource, #GrlMediaSource
+ *
+ * The registry holds the metadata of a set of plugins.
+ *
+ * The #GrlPluginRegistry object is a list of plugins and some functions
+ * for dealing with them. Each #GrlMediaPlugin is matched 1-1 with a file
+ * on disk, and may or may not be loaded a given time. There only can be
+ * a single instance of #GstPluginRegistry (singleton pattern).
+ *
+ * A #GrlMediaPlugin can hold several data sources (#GrlMetadataSource or
+ * #GrlMediaSource), and #GrlPluginRegistry and shall register each one of
+ * them.
+ */
+
 #include "grl-plugin-registry.h"
 #include "grl-media-plugin-priv.h"
 
@@ -76,6 +93,13 @@ grl_plugin_registry_class_init (GrlPluginRegistryClass *klass)
 
   g_type_class_add_private (klass, sizeof (GrlPluginRegistryPrivate));
 
+  /**
+   * GrlPluginRegistry::source-added:
+   * @registry: the registry
+   * @plugin: the plugin that has been added
+   *
+   * Signals that a plugin has been added to the registry.
+   */
   registry_signals[SIG_SOURCE_ADDED] =
     g_signal_new("source-added",
 		 G_TYPE_FROM_CLASS(klass),
@@ -86,6 +110,13 @@ grl_plugin_registry_class_init (GrlPluginRegistryClass *klass)
 		 g_cclosure_marshal_VOID__OBJECT,
 		 G_TYPE_NONE, 1, GRL_TYPE_MEDIA_PLUGIN);
 
+  /**
+   * GrlPluginRegistry::source-removed:
+   * @registry: the registry
+   * @plugin: the plugin that has been removed
+   *
+   * Signals that a plugin has been removed from the registry.
+   */
   registry_signals[SIG_SOURCE_REMOVED] =
     g_signal_new("source-removed",
 		 G_TYPE_FROM_CLASS(klass),
@@ -233,6 +264,17 @@ sort_by_rank (GrlMediaPlugin **source_list)
 
 /* ================ API ================ */
 
+/**
+ * grl_plugin_registry_get_instance:
+ *
+ * As the registry is designed to work as a singleton, this
+ * method is in charge of creating the only instance or
+ * returned it if it is already in memory.
+ *
+ * Returns: a new or an already created instance of the registry.
+ *
+ * It is NOT MT-safe
+ */
 GrlPluginRegistry *
 grl_plugin_registry_get_instance (void)
 {
@@ -245,6 +287,16 @@ grl_plugin_registry_get_instance (void)
   return registry;
 }
 
+/**
+ * grl_plugin_registry_register_source:
+ * @registry: the registry instance
+ * @plugin: the descriptor of the plugin which owns the srouce
+ * @source: the source to register
+ *
+ * Register a @source in the @registry with the given @plugin information
+ *
+ * Returns: %TRUE if success
+ */
 gboolean
 grl_plugin_registry_register_source (GrlPluginRegistry *registry,
                                      const GrlPluginInfo *plugin,
@@ -270,6 +322,13 @@ grl_plugin_registry_register_source (GrlPluginRegistry *registry,
   return TRUE;
 }
 
+/**
+ * grl_plugin_registry_unregister_source:
+ * @registry: the registry instance
+ * @source: the source to unregister
+ *
+ * Removes the @source from the @registry hash table
+ */
 void
 grl_plugin_registry_unregister_source (GrlPluginRegistry *registry,
                                        GrlMediaPlugin *source)
@@ -290,6 +349,15 @@ grl_plugin_registry_unregister_source (GrlPluginRegistry *registry,
   g_free (id);
 }
 
+/**
+ * grl_plugin_registry_load:
+ * @registry: the registry instance
+ * @path: the path to the so file
+ *
+ * Loads a module from shared object file stored in @path
+ *
+ * Returns: %TRUE if the module is loaded correctly
+ */
 gboolean
 grl_plugin_registry_load (GrlPluginRegistry *registry, const gchar *path)
 {
@@ -330,6 +398,16 @@ grl_plugin_registry_load (GrlPluginRegistry *registry, const gchar *path)
   return TRUE;
 }
 
+/**
+ * grl_plugin_registry_load_directory:
+ * @registry: the registry instance
+ * @path: the path to the directory
+ *
+ * Loads a set of modules from directory in @path which contains
+ * a group shared object files.
+ *
+ * Returns: %TRUE if the directory exists.
+ */
 gboolean
 grl_plugin_registry_load_directory (GrlPluginRegistry *registry,
                                     const gchar *path)
@@ -357,6 +435,18 @@ grl_plugin_registry_load_directory (GrlPluginRegistry *registry,
   return TRUE;
 }
 
+/**
+ * grl_plugin_registry_load_all:
+ * @registry: the registry instance
+ *
+ * Load all the modules available in the default directory path.
+ *
+ * The default directory path can be changed through the environment
+ * variable %GRL_PLUGIN_PATH and it can contain several paths separated
+ * by ":"
+ *
+ * Returns: %TRUE always
+ */
 gboolean
 grl_plugin_registry_load_all (GrlPluginRegistry *registry)
 {
@@ -382,6 +472,15 @@ grl_plugin_registry_load_all (GrlPluginRegistry *registry)
   return TRUE;
 }
 
+/**
+ * grl_plugin_registry_lookup_source:
+ * @registry: the registry instance
+ * @source_id: the id of a source
+ *
+ * This function will search and retrieve a source given its identifier.
+ *
+ * Returns: (allow-none): The source found.
+ */
 GrlMediaPlugin *
 grl_plugin_registry_lookup_source (GrlPluginRegistry *registry,
                                    const gchar *source_id)
@@ -390,6 +489,17 @@ grl_plugin_registry_lookup_source (GrlPluginRegistry *registry,
                                                  source_id);
 }
 
+/**
+ * grl_plugin_registry_get_sources:
+ * @registry: the registry instance
+ * @ranked: whether the returned list shall be returned ordered by rank
+ *
+ * This function will return all the available sources in the @registry.
+ *
+ * If @ranked is %TRUE, the source list will be ordered by rank.
+ *
+ * Returns: (transfer container): an array of available sources
+ */
 GrlMediaPlugin **
 grl_plugin_registry_get_sources (GrlPluginRegistry *registry,
 				 gboolean ranked)
@@ -412,6 +522,19 @@ grl_plugin_registry_get_sources (GrlPluginRegistry *registry,
   return source_list;
 }
 
+/**
+ * grl_plugin_registry_get_sources_by_capabilities:
+ * @registry: the registry instance
+ * @caps: a bitwise mangle of the requested capabilities.
+ * @ranked: whether the returned list shall be returned ordered by rank
+ *
+ * Give an array of all the available sources in the @registry capable of
+ * the operations requested in @caps.
+ *
+ * If @ranked is %TRUE, the source list will be ordered by rank.
+ *
+ * Returns: (transfer container): an array of available sources
+ */
 GrlMediaPlugin **
 grl_plugin_registry_get_sources_by_capabilities (GrlPluginRegistry *registry,
 						 GrlSupportedOps caps,
@@ -443,6 +566,14 @@ grl_plugin_registry_get_sources_by_capabilities (GrlPluginRegistry *registry,
   return source_list;  
 }
 
+/**
+ * grl_plugin_registry_unload:
+ * @registry: the registry instance
+ * @plugin_id: the identifier of the plugin
+ *
+ * Unload from memory a module identified by @plugin_id. This means call the
+ * module's deinit function.
+ */
 void
 grl_plugin_registry_unload (GrlPluginRegistry *registry,
                             const gchar *plugin_id)
@@ -461,6 +592,15 @@ grl_plugin_registry_unload (GrlPluginRegistry *registry,
   }
 }
 
+/**
+ * grl_plugin_registry_lookup_metadata_key:
+ * @registry: the registry instance
+ * @key_id: the key identifier
+ *
+ * Look up for the metadata key structure givne the @key_id.
+ *
+ * Returns: (transfer none): The metadata key structure.
+ */
 const GrlMetadataKey *
 grl_plugin_registry_lookup_metadata_key (GrlPluginRegistry *registry,
                                          GrlKeyID key_id)
diff --git a/src/grl-plugin-registry.h b/src/grl-plugin-registry.h
index fe9d371..3debca4 100644
--- a/src/grl-plugin-registry.h
+++ b/src/grl-plugin-registry.h
@@ -63,6 +63,22 @@
 
 /* Plugin registration */
 
+/**
+ * GRL_PLUGIN_REGISTER:
+ * @init: the module initialization. It shall instantiate the
+ * the #GrlMediaPlugins provided
+ * @deinit: (allow-none): function to execute when the registry needs to dispose the module
+ * @id: the module identifier
+ * @name: the module name
+ * @desc: a phrase describing the service provided by the module
+ * @version: the version string of the module
+ * @author: the author(s) of the module
+ * @license: the license used by the module
+ * @site: the website of the module
+ *
+ * Define the boilerplate for loadable modules. Defines a new module
+ * descriptor which provides a set of #GrlMediaPlugins
+ */
 #define GRL_PLUGIN_REGISTER(init,               \
                             deinit,             \
                             id,                 \
@@ -90,6 +106,19 @@
 
 typedef struct _GrlPluginRegistry GrlPluginRegistry;
 
+/**
+ * GrlPluginInfo:
+ * @id: the module identifier
+ * @name: the module name
+ * @desc: a phrase describing the service provided by the module
+ * @version: the version string of the module
+ * @author: the author(s) of the module
+ * @license: the license used by the module
+ * @site: the website of the module
+ * @rank: the plugin priority rank
+ *
+ * This structure stores the information related to a module
+ */
 typedef struct _GrlPluginInfo {
   const gchar *id;
   const gchar *name;
@@ -101,14 +130,42 @@ typedef struct _GrlPluginInfo {
   gint rank;
 } GrlPluginInfo;
 
-typedef struct _GrlPluginDescriptor {
+typedef struct _GrlPluginDescriptor  GrlPluginDescriptor;
+
+/**
+* GrlPluginDescriptor:
+* @info: the module information
+* @plugin_init: the module initialization. It shall instantiate the
+* the #GrlMediaPlugins provided
+* @plugin_deinit: function to execute when the registry needs
+* to dispose the module.
+*
+* This structure is used for the module loader
+*/
+struct _GrlPluginDescriptor {
   GrlPluginInfo info;
   gboolean (*plugin_init) (GrlPluginRegistry *, const GrlPluginInfo *);
   void (*plugin_deinit) (void);
-} GrlPluginDescriptor;
+};
 
 /* Plugin ranks */
 
+/**
+ * GrlPluginRank:
+ * @GRL_PLUGIN_RANK_LOWEST: will be chosen last or not at all
+ * @GRL_PLUGIN_RANK_LOW: unlikely to be chosen
+ * @GRL_PLUGIN_RANK_DEFAULT: likely to be chosen
+ * @GRL_PLUGIN_RANK_HIGH: will be chosen
+ * @GRL_PLUGIN_RANK_HIGHEST: will be chosen first
+ *
+ * Module priority ranks. Defines the order in which the resolver
+ * (or similar rank-picking mechanisms) will choose this plugin
+ * over an alternative one with the same function.
+ *
+ * These constants serve as a rough guidance for defining the rank
+ * of a GrlPluginInfo. Any value is valid, including values bigger
+ * than GRL_PLUGIN_RANK_HIGHEST.
+ */
 typedef enum {
   GRL_PLUGIN_RANK_LOWEST  = -64,
   GRL_PLUGIN_RANK_LOW     = -32,
@@ -133,6 +190,12 @@ struct _GrlPluginRegistry {
 
 typedef struct _GrlPluginRegistryClass GrlPluginRegistryClass;
 
+/**
+ * GrlPluginRegistryClass:
+ * @parent_class: the parent class structure
+ *
+ * Grilo PluginRegistry class. Dynamic loader of plugins.
+ */
 struct _GrlPluginRegistryClass {
 
   GObjectClass parent_class;