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

Logging API docs See merge request libfprint/libfprint!16
2018-09-07 10:59:56 +00:00 · 2018-09-07 10:59:56 +00:00 · d7af9a4498
commit d7af9a4498
parent 561576961c 3cb3b1d63a
6 changed files with 111 additions and 39 deletions
--- a/doc/libfprint-docs.xml
+++ b/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>
--- a/doc/libfprint-sections.txt
+++ b/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>
--- a/libfprint/drivers_api.h
+++ b/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);
--- a/libfprint/fp_internal.h
+++ b/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,
--- a/libfprint/fpi-log.h
+++ b/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
--- a/libfprint/meson.build
+++ b/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',