doc: Port from Doxygen to gtk-doc

Split the introduction into separate chapters, add filler documentation
for async functions, fix mismatched function arguments.

doc/advanced-topics.xml

@@ -0,0 +1,115 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<chapter id="advanced-topics" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <title>Advanced Topics</title>
+
+  <refsect2 id="compatibility">
+    <title>Device and print compatibility</title>
+
+    <para>
+    Moving off generic conceptual ideas and onto libfprint-specific
+    implementation details, here are some introductory notes regarding how
+    libfprint copes with compatibility of fingerprints.
+    </para>
+
+    <para>
+    libfprint deals with a whole variety of different fingerprint readers and
+    the design includes considerations of compatibility and interoperability
+    between multiple devices. Your application should also be prepared to
+    work with more than one type of fingerprint reader and should consider that
+    enrolled fingerprint X may not be compatible with the device the user has
+    plugged in today.
+    </para>
+
+    <para>
+    libfprint implements the principle that fingerprints from different devices
+    are not necessarily compatible. For example, different devices may see
+    significantly different areas of fingerprint surface, and comparing images
+    between the devices would be unreliable. Also, devices can stretch and
+    distort images in different ways.
+    </para>
+
+    <para>
+    libfprint also implements the principle that in some cases, fingerprints
+    <emphasis>are</emphasis> compatible between different devices. If you go and buy two
+    identical fingerprint readers, it seems logical that you should be able
+    to enroll on one and verify on another without problems.
+    </para>
+
+    <para>
+    libfprint takes a fairly simplistic approach to these issues. Internally,
+    fingerprint hardware is driven by individual drivers. libfprint enforces
+    that a fingerprint that came from a device backed by driver X is never
+    compared to a fingerprint that came from a device backed by driver Y.
+    </para>
+
+    <para>
+    Additionally, libfprint is designed for the situation where a single driver
+    may support a range of devices which differ in imaging or scanning
+    properties. For example, a driver may support two ranges of devices which
+    even though are programmed over the same interface, one device sees
+    substantially less of the finger flesh, therefore images from the two
+    device types should be incompatible despite being from the same driver. To
+    implement this, each driver assigns a <emphasis>device type</emphasis> to each device
+    that it detects based on its imaging characteristics. libfprint ensures that
+    two prints being compared have the same device type.
+    </para>
+
+    <para>
+    In summary, libfprint represents fingerprints in several internal structures
+    and each representation will offer you a way of determining the
+    \ref driver_id "driver ID" and \ref devtype "devtype" of the print in
+    question. Prints are only compatible if the driver ID <emphasis role="strong">and</emphasis> devtypes
+    match. libfprint does offer you some "is this print compatible?" helper
+    functions, so you don't have to worry about these details too much.
+    </para>
+  </refsect2>
+
+  <refsect2 id="driver_id">
+    <title>Driver IDs</title>
+
+    <para>
+    Each driver is assigned a unique ID by the project maintainer. These
+    assignments are
+    <ulink href="http://www.reactivated.net/fprint/Driver_ID_assignments">
+    documented on the wiki</ulink> and will never change.
+    </para>
+
+    <para>
+    The only reason you may be interested in retrieving the driver ID for a
+    driver is for the purpose of checking if some print data is compatible
+    with a device. libfprint uses the driver ID as one way of checking that
+    the print you are trying to verify is compatible with the device in
+    question - it ensures that enrollment data from one driver is never fed to
+    another. Note that libfprint does provide you with helper functions to
+    determine whether a print is compatible with a device, so under most
+    circumstances, you don't have to worry about driver IDs at all.
+    </para>
+  </refsect2>
+
+  <refsect2 id="device-types">
+    <title>Device types</title>
+
+    <para>
+    Internally, the \ref drv "driver" behind a device assigns a 32-bit
+    <emphasis>devtype</emphasis> identifier to the device. This cannot be used as a unique
+    ID for a specific device as many devices under the same range may share
+    the same devtype. The devtype may even be 0 in all cases.
+    </para>
+
+    <para>
+    The only reason you may be interested in retrieving the devtype for a
+    device is for the purpose of checking if some print data is compatible
+    with a device. libfprint uses the devtype as one way of checking that the
+    print you are verifying is compatible with the device in question - the
+    devtypes must be equal. This effectively allows drivers to support more
+    than one type of device where the data from each one is not compatible with
+    the other. Note that libfprint does provide you with helper functions to
+    determine whether a print is compatible with a device, so under most
+    circumstances, you don't have to worry about devtypes at all.
+    </para>
+  </refsect2>
+
+</chapter>

doc/getting-started.xml

@@ -0,0 +1,30 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<chapter id="getting-started" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <title>Getting Started</title>
+
+  <para>
+  libfprint includes several simple functional examples under the examples/
+  directory in the libfprint source distribution. Those are good starting
+  points.
+  </para>
+
+  <para>
+  Usually the first thing you want to do is determine which fingerprint
+  devices are present. This is done through \ref dscv_dev "device discovery".
+  </para>
+
+  <para>
+  Once you have found a device you would like to operate, you should open it.
+  Refer to \ref dev "device operations". This section also details enrollment,
+  image capture, and verification.
+  </para>
+
+  <para>
+  That should be enough to get you started, but do remember there are
+  documentation pages on other aspects of libfprint's API (see the modules
+  page).
+  </para>
+</chapter>

doc/intro.xml

@@ -0,0 +1,106 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+<chapter id="intro" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <title>Introduction</title>
+
+  <para>
+  libfprint is an open source library to provide access to fingerprint
+  scanning devices. For more info, see the
+  <ulink url="http://www.reactivated.net/fprint/Libfprint">libfprint project homepage</ulink>.
+  </para>
+
+  <para>
+  This documentation is aimed at application developers who wish to integrate
+  fingerprint-related functionality into their software. libfprint has been
+  designed so that you only have to do this once - by integrating your
+  software with libfprint, you'll be supporting all the fingerprint readers
+  that we have got our hands on. As such, the API is rather general (and
+  therefore hopefully easy to comprehend!), and does its best to hide the
+  technical details that required to operate the hardware.
+  </para>
+
+  <para>
+  This documentation is not aimed at developers wishing to develop and
+  contribute fingerprint device drivers to libfprint.
+  </para>
+
+  <para>
+  Feedback on this API and its associated documentation is appreciated. Was
+  anything unclear? Does anything seem unreasonably complicated? Is anything
+  missing? Let us know on the
+  <ulink url="http://www.reactivated.net/fprint/Mailing_list">mailing list</ulink>.
+  </para>
+
+  <refsect2 id="enrollment">
+    <title>Enrollment</title>
+
+    <para>
+    Before you dive into the API, it's worth introducing a couple of concepts.
+    </para>
+
+    <para>
+    The process of enrolling a finger is where you effectively scan your
+    finger for the purposes of teaching the system what your finger looks like.
+    This means that you scan your fingerprint, then the system processes it and
+    stores some data about your fingerprint to refer to later.
+    </para>
+  </refsect2>
+
+  <refsect2 id="verification">
+    <title>Verification</title>
+
+    <para>
+    Verification is what most people think of when they think about fingerprint
+    scanning. The process of verification is effectively performing a fresh
+    fingerprint scan, and then comparing that scan to a finger that was
+    previously enrolled.
+    </para>
+
+    <para>
+    As an example scenario, verification can be used to implement what people
+    would picture as fingerprint login (i.e. fingerprint replaces password).
+    For example:
+    </para>
+    <itemizedlist mark='dot'>
+      <listitem>
+       I enroll my fingerprint through some software that trusts I am who I say
+       I am. This is a prerequisite before I can perform fingerprint-based
+       login for my account.
+      </listitem>
+      <listitem>
+       Some time later, I want to login to my computer. I enter my username,
+       but instead of prompting me for a password, it asks me to scan my finger.
+       I scan my finger.
+      </listitem>
+      <listitem>
+       The system compares the finger I just scanned to the one that was
+       enrolled earlier. If the system decides that the fingerprints match,
+       I am successfully logged in. Otherwise, the system informs me that I am
+       not authorised to login as that user.
+      </listitem>
+    </itemizedlist>
+  </refsect2>
+
+  <refsect2 id="identification">
+    <title>Identification</title>
+
+    <para>
+    Identification is the process of comparing a freshly scanned fingerprint
+    to a <emphasis>collection</emphasis> of previously enrolled fingerprints. For example,
+    imagine there are 100 people in an organisation, and they all have enrolled
+    their fingerprints. One user walks up to a fingerprint scanner and scans
+    their finger. With <emphasis>no other knowledge</emphasis> of who that user might be,
+    the system examines their fingerprint, looks in the database, and determines
+    that the user is user number #61.
+    </para>
+
+    <para>
+    In other words, verification might be seen as a one-to-one fingerprint
+    comparison where you know the identity of the user that you wish to
+    authenticate, whereas identification is a one-to-many comparison where you
+    do not know the identity of the user that you wish to authenticate.
+    </para>
+  </refsect2>
+</chapter>

doc/libfprint-docs.xml

@@ -0,0 +1,53 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<book id="index">
+  <bookinfo>
+    <title>libfprint Reference Manual</title>
+    <releaseinfo>
+      <para>This document is the API reference for the libfprint library.</para>
+      <para>
+        The latest version of libfprint, as well as the latest version of
+        this API reference, is <ulink role="online-location" url="https://www.freedesktop.org/wiki/Software/fprint/libfprint/">available online</ulink>.
+      </para>
+    </releaseinfo>
+  </bookinfo>
+
+  <part>
+    <title>Library Overview</title>
+    <xi:include href="intro.xml"/>
+    <xi:include href="advanced-topics.xml"/>
+    <xi:include href="getting-started.xml"/>
+  </part>
+
+  <part>
+    <title>API Documentation</title>
+    <xi:include href="xml/events.xml"/>
+    <xi:include href="xml/discovery.xml"/>
+
+    <xi:include href="xml/drv.xml"/>
+    <xi:include href="xml/dev.xml"/>
+    <xi:include href="xml/print_data.xml"/>
+    <!-- https://bugs.freedesktop.org/show_bug.cgi?id=106550
+    <xi:include href="xml/dscv_print.xml"/> -->
+    <xi:include href="xml/img.xml"/>
+  </part>
+
+  <!--
+  <part>
+    <title>Writing Drivers</title>
+  </part>
+  -->
+
+  <index id="api-index">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+</book>

doc/libfprint-sections.txt

@@ -0,0 +1,127 @@
+<INCLUDE>fprint.h</INCLUDE>
+
+<SECTION>
+<FILE>events</FILE>
+<TITLE>Initialisation and events handling</TITLE>
+fp_set_debug
+fp_init
+fp_exit
+fp_pollfd
+fp_handle_events_timeout
+fp_handle_events
+fp_get_next_timeout
+fp_get_pollfds
+fp_set_pollfd_notifiers
+</SECTION>
+
+<SECTION>
+<FILE>discovery</FILE>
+<TITLE>Device discovery</TITLE>
+fp_dscv_dev
+fp_discover_devs
+fp_dscv_devs_free
+fp_dscv_dev_get_driver
+fp_dscv_dev_get_devtype
+fp_dscv_dev_supports_print_data
+fp_dscv_dev_supports_dscv_print
+fp_dscv_dev_for_print_data
+fp_dscv_dev_for_dscv_print
+</SECTION>
+
+<SECTION>
+<FILE>drv</FILE>
+fp_driver
+fp_driver_get_name
+fp_driver_get_full_name
+fp_driver_get_driver_id
+fp_driver_get_scan_type
+</SECTION>
+
+<SECTION>
+<FILE>dev</FILE>
+fp_dev
+fp_scan_type
+fp_capture_result
+fp_enroll_result
+fp_verify_result
+
+fp_dev_get_driver
+fp_dev_get_nr_enroll_stages
+fp_dev_get_devtype
+fp_dev_supports_print_data
+fp_dev_supports_imaging
+fp_dev_supports_identification
+fp_dev_supports_dscv_print
+fp_dev_get_img_width
+fp_dev_get_img_height
+
+fp_dev_open
+fp_async_dev_open
+
+fp_dev_close
+fp_async_dev_close
+
+fp_enroll_finger
+fp_enroll_finger_img
+fp_async_enroll_start
+fp_async_enroll_stop
+
+fp_verify_finger
+fp_verify_finger_img
+fp_async_verify_start
+fp_async_verify_stop
+
+fp_identify_finger
+fp_identify_finger_img
+fp_async_identify_start
+fp_async_identify_stop
+
+fp_dev_img_capture
+fp_async_capture_start
+fp_async_capture_stop
+</SECTION>
+
+<SECTION>
+<FILE>print_data</FILE>
+fp_finger
+fp_print_data
+fp_print_data
+fp_print_data_get_data
+fp_print_data_from_data
+fp_print_data_save
+fp_print_data_load
+fp_print_data_delete
+fp_print_data_from_dscv_print
+fp_print_data_free
+fp_print_data_get_driver_id
+fp_print_data_get_devtype
+</SECTION>
+
+<SECTION>
+<FILE>dscv_print</FILE>
+fp_dscv_print
+fp_discover_prints
+fp_dscv_prints_free
+fp_dscv_print_get_driver_id
+fp_dscv_print_get_devtype
+fp_dscv_print_get_finger
+fp_dscv_print_delete
+</SECTION>
+
+<SECTION>
+<FILE>img</FILE>
+fp_img
+fp_minutia
+fp_img_free
+fp_img_get_height
+fp_img_get_width
+fp_img_get_data
+fp_img_save_to_file
+fp_img_standardize
+fp_img_binarize
+fp_img_get_minutiae
+</SECTION>
+
+<SECTION>
+<FILE>poll</FILE>
+</SECTION>

doc/meson.build

@@ -1,17 +1,67 @@
-cdata = configuration_data()
-cdata.set('SRCDIR', join_paths(meson.source_root(), 'libfprint'))
-cdata.set('BUILDDIR', join_paths(meson.build_root(), 'doc'))
+subdir('xml')
 
-cfg = configure_file(input: 'doxygen.cfg.in',
-                     output: 'doxygen.cfg',
-                     configuration: cdata,
-                     install: false)
+private_headers = [
+  'config.h',
 
-doxygen = find_program('doxygen')
-datadir = join_paths(get_option('datadir'), 'doc', 'libfprint-devel')
-custom_target('docs',
-              input: cfg,
-              output: 'html',
-              command: [ doxygen, '@INPUT@' ],
-              install: true,
-              install_dir: datadir)
+  'aeslib.h',
+  'assembling.h',
+  'fp_internal.h',
+
+  # Drivers
+  'aes1660.h',
+  'aes2501.h',
+  'aes2550.h',
+  'aes2660.h',
+  'aes3k.h',
+  'aesx660.h',
+  'driver_ids.h',
+  'elan.h',
+  'upeksonly.h',
+  'upektc.h',
+  'upektc_img.h',
+  'vfs0050.h',
+  'vfs301_proto_fragments.h',
+  'vfs301_proto.h',
+  'vfs5011_proto.h',
+
+  # NBIS
+  'morph.h',
+  'sunrast.h',
+  'bozorth.h',
+  'defs.h',
+  'log.h',
+  'bz_array.h',
+  'lfs.h',
+]
+
+html_images = [
+]
+
+content_files = [
+  'intro.xml'
+]
+
+expand_content_files = content_files
+
+glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
+glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
+docpath = join_paths(get_option('datadir'), 'gtk-doc', 'html')
+
+gnome.gtkdoc('libfprint',
+             main_xml: 'libfprint-docs.xml',
+             src_dir: join_paths(meson.source_root(), 'libfprint'),
+             dependencies: libfprint_dep,
+             content_files: content_files,
+             expand_content_files: expand_content_files,
+             scan_args: [
+               '--rebuild-types',
+               '--ignore-decorators=API_EXPORTED',
+               '--ignore-headers=' + ' '.join(private_headers),
+             ],
+             fixxref_args: [
+               '--html-dir=@0@'.format(docpath),
+               '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
+               '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
+             ],
+             html_assets: html_images,
+             install: true)

doc/xml/gtkdocentities.ent.in

@@ -0,0 +1,8 @@
+<!ENTITY package "@PACKAGE@">
+<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
+<!ENTITY package_name "@PACKAGE_NAME@">
+<!ENTITY package_string "@PACKAGE_STRING@">
+<!ENTITY package_tarname "@PACKAGE_TARNAME@">
+<!ENTITY package_url "@PACKAGE_URL@">
+<!ENTITY package_version "@PACKAGE_VERSION@">
+<!ENTITY package_api_version "@PACKAGE_API_VERSION@">

doc/xml/meson.build

@@ -0,0 +1,10 @@
+ent_conf = configuration_data()
+ent_conf.set('PACKAGE', 'libfprint')
+ent_conf.set('PACKAGE_BUGREPORT', 'https://bugs.freedesktop.org/enter_bug.cgi?product=libfprint')
+ent_conf.set('PACKAGE_NAME', 'libfprint')
+ent_conf.set('PACKAGE_STRING', 'libfprint')
+ent_conf.set('PACKAGE_TARNAME', 'libfprint-' + meson.project_version())
+ent_conf.set('PACKAGE_URL', 'https://www.freedesktop.org/wiki/Software/fprint/libfprint/')
+ent_conf.set('PACKAGE_VERSION', meson.project_version())
+ent_conf.set('PACKAGE_API_VERSION', '1.0')
+configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf)