[core 5/6] log: rename grl_log_init() to grl_log_configure()

[Víctor Manuel Jáquez Leal <vjaquez igalia com>]

From: Damien Lespiau <damien lespiau intel com>

You can configure one or several log domains at run time with this API,
so it's not an initialization per se, it's closer to a configuration
string one gives to the log system.

Along with the renaming, properly document the format of the string used
to configure log domains.

https://bugzilla.gnome.org/show_bug.cgi?id=627864
---
 doc/reference/quick-start-using-grilo.xml |    8 +++---
 src/grl-log.c                             |   42 +++++++++++++++++++++++++---
 src/grl-log.h                             |    2 +-
 3 files changed, 42 insertions(+), 10 deletions(-)

diff --git a/doc/reference/quick-start-using-grilo.xml b/doc/reference/quick-start-using-grilo.xml
index 86f354c..cd8fabf 100644
--- a/doc/reference/quick-start-using-grilo.xml
+++ b/doc/reference/quick-start-using-grilo.xml
@@ -105,7 +105,7 @@ main (int argc, gchar *argv[])
   GMainLoop *loop;
 
   grl_init (&argc, &argv);
-  grl_log_init ("example:*"); /* Filter debug output */
+  grl_log_configure ("example:*"); /* Filter debug output */
   load_plugins ();            /* Load Grilo plugins */
 
   /* Run the main loop */
@@ -243,7 +243,7 @@ main (int argc, gchar *argv[])
 {
   GMainLoop *loop;
   grl_init (&argc, &argv);
-  grl_log_init ("example:*");
+  grl_log_configure ("example:*");
   load_plugins ();
   loop = g_main_loop_new (NULL, FALSE);
   g_main_loop_run (loop);
@@ -352,7 +352,7 @@ main (int argc, gchar *argv[])
 {
   GMainLoop *loop;
   grl_init (&argc, &argv);
-  grl_log_init ("example:*");
+  grl_log_configure ("example:*");
   load_plugins ();
   loop = g_main_loop_new (NULL, FALSE);
   g_main_loop_run (loop);
@@ -563,7 +563,7 @@ main (int argc, gchar *argv[])
     target_source_id = argv[1];
   }
 
-  grl_log_init ("example:*");
+  grl_log_configure ("example:*");
   load_plugins ();
   loop = g_main_loop_new (NULL, FALSE);
   g_main_loop_run (loop);
diff --git a/src/grl-log.c b/src/grl-log.c
index afd4108..0bbbe0c 100644
--- a/src/grl-log.c
+++ b/src/grl-log.c
@@ -103,7 +103,7 @@ grl_log_domain_new (const gchar *name)
     domain_spec = pair_info[0];
 
     if (g_strcmp0 (domain_spec, name) == 0)
-      grl_log_init (*pair);
+      grl_log_configure (*pair);
 
     g_strfreev (pair_info);
     pair++;
@@ -199,7 +199,7 @@ get_log_level_from_spec (const gchar *level_spec)
 }
 
 static void
-setup_log_domains (const gchar *domains)
+configure_log_domains (const gchar *domains)
 {
   gchar **pairs;
   gchar **pair;
@@ -310,7 +310,7 @@ _grl_log_init_core_domains (void)
   log_env = g_getenv ("GRL_DEBUG");
   if (log_env) {
     GRL_DEBUG ("Using log configuration from GRL_DEBUG: %s", log_env);
-    setup_log_domains (log_env);
+    configure_log_domains (log_env);
     grl_log_env = g_strsplit (log_env, ",", 0);
   }
 
@@ -340,8 +340,40 @@ _grl_log_free_core_domains (void)
 
 #undef DOMAIN_FREE
 
+/**
+ * grl_log_configure:
+ * @config: A string describing the wanted log configuration
+ *
+ * Configure a set of log domains. The default configuration is to display
+ * warning and error messages only for all the log domains.
+ *
+ * The configuration string follows the following grammar:
+ *
+ * |[
+ *   config-list: config | config ',' config-list
+ *   config: domain ':' level
+ *   domain: '*' | [a-zA-Z0-9]+
+ *   level: '*' | '-' | named-level | num-level
+ *   named-level: "none" | "error" | "warning" | "message" | "info" | "debug"
+ *   num-level: [0-5]
+ * ]|
+ *
+ * examples:
+ * <itemizedlist>
+ *   <listitem><para>"*:*": maximum verbosity for all the log domains</para>
+ *   </listitem>
+ *   <listitem><para>"*:-": don't print any message</para></listitem>
+ *   <listitem><para>"media-source:debug,metadata-source:debug": prints debug,
+ *   info, message warning and error messages for the media-source and
+ *   metadata-source log domains</para></listitem>
+ * </itemizedlist>
+ *
+ * <note>It's possible to override the log configuration at runtime by
+ * defining the GRL_DEBUG environment variable to a configuration string
+ * as described above</note>
+ */
 void
-grl_log_init (const gchar *domains)
+grl_log_configure (const gchar *config)
 {
-  setup_log_domains (domains);
+  configure_log_domains (config);
 }
diff --git a/src/grl-log.h b/src/grl-log.h
index 921f124..76a1e38 100644
--- a/src/grl-log.h
+++ b/src/grl-log.h
@@ -268,7 +268,7 @@ GRL_DEBUG (GrlLogDomain *domain, const char *format, ...)
 GrlLogDomain *  grl_log_domain_new    (const gchar *name);
 void            grl_log_domain_free   (GrlLogDomain *domain);
 
-void            grl_log_init          (const gchar  *domains);
+void            grl_log_configure     (const gchar  *config);
 void            grl_log               (GrlLogDomain *domain,
                                        GrlLogLevel   level,
                                        const gchar  *strloc,
-- 
1.7.1