Merge branch 'wip/hadess/fpi-log-docs' into 'master'

Logging API docs

See merge request libfprint/libfprint!16

doc/libfprint-docs.xml

@@ -38,6 +38,7 @@
 
   <part>
     <title>Writing Drivers</title>
+    <xi:include href="xml/fpi-log.xml"/>
     <xi:include href="xml/fpi-ssm.xml"/>
     <xi:include href="xml/fpi-poll.xml"/>
   </part>

doc/libfprint-sections.txt

@@ -141,6 +141,17 @@ fp_img_get_minutiae
 <FILE>poll</FILE>
 </SECTION>
 
+<SECTION>
+<INCLUDE>fpi-log.h</INCLUDE>
+<FILE>fpi-log</FILE>
+fp_dbg
+fp_info
+fp_warn
+fp_err
+BUG_ON
+BUG
+</SECTION>
+
 <SECTION>
 <INCLUDE>fpi-ssm.h</INCLUDE>
 <FILE>fpi-ssm</FILE>

libfprint/drivers_api.h

@@ -22,12 +22,6 @@
 #define __DRIVERS_API_H__
 
 #include <config.h>
-
-#ifdef FP_COMPONENT
-#undef G_LOG_DOMAIN
-#define G_LOG_DOMAIN "libfprint-"FP_COMPONENT
-#endif
-
 #include <stdint.h>
 #include <errno.h>
 #include <string.h>
@@ -36,25 +30,12 @@
 #include <libusb.h>
 
 #include "fprint.h"
+#include "fpi-log.h"
 #include "fpi-ssm.h"
 #include "fpi-poll.h"
 #include "assembling.h"
 #include "drivers/driver_ids.h"
 
-#define fp_dbg g_debug
-#define fp_info g_debug
-#define fp_warn g_warning
-#define fp_err g_warning
-
-#define BUG_ON(condition) G_STMT_START		\
-	if (condition) {			\
-		char *s;			\
-		s = g_strconcat ("BUG: (", #condition, ")", NULL); \
-		g_warning ("%s: %s() %s:%d", s, G_STRFUNC, __FILE__, __LINE__); \
-		g_free (s);			\
-	} G_STMT_END
-#define BUG() BUG_ON(1)
-
 struct fp_dev;
 libusb_device_handle *fpi_dev_get_usb_dev(struct fp_dev *dev);
 void *fpi_dev_get_user_data (struct fp_dev *dev);

libfprint/fp_internal.h

@@ -22,37 +22,19 @@
 
 #include <config.h>
 
-#ifdef FP_COMPONENT
-#undef G_LOG_DOMAIN
-#define G_LOG_DOMAIN "libfprint-"FP_COMPONENT
-#endif
-
 #include <stdint.h>
 #include <errno.h>
 #include <glib.h>
 #include <libusb.h>
 
 #include "fprint.h"
+#include "fpi-log.h"
 #include "drivers/driver_ids.h"
 
 #define container_of(ptr, type, member) ({                      \
         const typeof( ((type *)0)->member ) *__mptr = (ptr);    \
         (type *)( (char *)__mptr - offsetof(type,member) );})
 
-#define fp_dbg g_debug
-#define fp_info g_debug
-#define fp_warn g_warning
-#define fp_err g_warning
-
-#define BUG_ON(condition) G_STMT_START		\
-	if (condition) {			\
-		char *s;			\
-		s = g_strconcat ("BUG: (", #condition, ")", NULL); \
-		g_warning ("%s: %s() %s:%d", s, G_STRFUNC, __FILE__, __LINE__); \
-		g_free (s);			\
-	} G_STMT_END
-#define BUG() BUG_ON(1)
-
 enum fp_dev_state {
 	DEV_STATE_INITIAL = 0,
 	DEV_STATE_ERROR,

libfprint/fpi-log.h

@@ -0,0 +1,96 @@
+/*
+ * Logging
+ * Copyright (C) 2007-2008 Daniel Drake <dsd@gentoo.org>
+ * Copyright (C) 2018 Bastien Nocera <hadess@hadess.net>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#ifndef __FPI_LOG_H__
+#define __FPI_LOG_H__
+
+/**
+ * SECTION:fpi-log
+ * @title: Logging
+ *
+ * Logging in libfprint is handled through GLib's logging system, and behave the same
+ * way as in the GLib [Message Output and Debugging Functions](https://developer.gnome.org/glib/stable/glib-Message-Logging.html)
+ * documentation.
+ *
+ * You should include `fpi-log.h` as early as possible in your sources, just after
+ * setting the `FP_COMPONENT` define to a string unique to your sources. This will
+ * set the suffix of the `G_LOG_DOMAIN` used for printing.
+ */
+
+#ifdef FP_COMPONENT
+#undef G_LOG_DOMAIN
+#define G_LOG_DOMAIN "libfprint-"FP_COMPONENT
+#endif
+
+#include <glib.h>
+
+/**
+ * fp_dbg:
+ *
+ * Same as g_debug().
+ *
+ */
+#define fp_dbg g_debug
+
+/**
+ * fp_info:
+ *
+ * Same as g_debug().
+ */
+#define fp_info g_debug
+
+/**
+ * fp_warn:
+ *
+ * Same as g_warning().
+ */
+#define fp_warn g_warning
+
+/**
+ * fp_err:
+ *
+ * Same as g_warning(). In the future, this might be changed to a
+ * g_assert() instead, so bear this in mind when adding those calls
+ * to your driver.
+ */
+#define fp_err g_warning
+
+/**
+ * BUG_ON:
+ * @condition: the condition to check
+ *
+ * Uses fp_err() to print an error if the @condition is true.
+ */
+#define BUG_ON(condition) G_STMT_START		\
+	if (condition) {			\
+		char *s;			\
+		s = g_strconcat ("BUG: (", #condition, ")", NULL); \
+		fp_err ("%s: %s() %s:%d", s, G_STRFUNC, __FILE__, __LINE__); \
+		g_free (s);			\
+	} G_STMT_END
+
+/**
+ * BUG:
+ *
+ * Same as BUG_ON() but is always true.
+ */
+#define BUG() BUG_ON(1)
+
+#endif

libfprint/meson.build

@@ -4,6 +4,7 @@ libfprint_sources = [
     'async.c',
     'core.c',
     'data.c',
+    'fpi-log.h',
     'fpi-ssm.c',
     'fpi-ssm.h',
     'fpi-poll.h',