depau/libfprint
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

docs: Update API documentation

Browse source 
Fixes to layout, dead links, typography, and more.

Thanks to Benjamin Berg <bberg@redhat.com> for the thorough review
This commit is contained in:
Bastien Nocera 2018-05-18 05:51:58 +02:00
parent f59bf389d9
commit b3fe4a1e91
8 changed files with 25 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
doc/advanced-topics.xml
View file

@ -60,7 +60,7 @@
<para> <para>
In summary, libfprint represents fingerprints in several internal structures In summary, libfprint represents fingerprints in several internal structures
and each representation will offer you a way of determining the and each representation will offer you a way of determining the
\ref driver_id "driver ID" and \ref devtype "devtype" of the print in <ulink url="#driver_id">driver ID</ulink> and <ulink url="#device-types">devtype</ulink> of the print in
question. Prints are only compatible if the driver ID <emphasis role="strong">and</emphasis> devtypes 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 match. libfprint does offer you some "is this print compatible?" helper
functions, so you don't have to worry about these details too much. functions, so you don't have to worry about these details too much.
@ -73,7 +73,7 @@
<para> <para>
Each driver is assigned a unique ID by the project maintainer. These Each driver is assigned a unique ID by the project maintainer. These
assignments are assignments are
<ulink href="http://www.reactivated.net/fprint/Driver_ID_assignments"> <ulink url="http://www.reactivated.net/fprint/Driver_ID_assignments">
documented on the wiki</ulink> and will never change. documented on the wiki</ulink> and will never change.
</para> </para>
@ -93,7 +93,7 @@
<title>Device types</title> <title>Device types</title>
<para> <para>
Internally, the \ref drv "driver" behind a device assigns a 32-bit Internally, the <ulink url="libfprint-Driver-operations.html#libfprint-Driver-operations.description">driver</ulink> behind a device assigns a 32-bit
<emphasis>devtype</emphasis> identifier to the device. This cannot be used as a unique <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 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. the same devtype. The devtype may even be 0 in all cases.

6
doc/getting-started.xml
View file

@ -6,19 +6,19 @@
<title>Getting Started</title> <title>Getting Started</title>
<para> <para>
libfprint includes several simple functional examples under the examples/ libfprint includes several simple functional examples under the <computeroutput>examples/</computeroutput>
directory in the libfprint source distribution. Those are good starting directory in the libfprint source distribution. Those are good starting
points. points.
</para> </para>
<para> <para>
Usually the first thing you want to do is determine which fingerprint Usually the first thing you want to do is determine which fingerprint
devices are present. This is done through \ref dscv_dev "device discovery". devices are present. This is done through <ulink url="libfprint-Device-discovery.html">device discovery</ulink>.
</para> </para>
<para> <para>
Once you have found a device you would like to operate, you should open it. 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, Refer to <ulink url="libfprint-Devices-operations.html">device operations</ulink>. This section also details enrollment,
image capture, and verification. image capture, and verification.
</para> </para>

2
doc/intro.xml
View file

@ -14,7 +14,7 @@
<para> <para>
This documentation is aimed at application developers who wish to integrate This documentation is aimed at application developers who wish to integrate
fingerprint-related functionality into their software. libfprint has been fingerprint-related functionality into their software. libfprint has been
designed so that you only have to do this once - by integrating your designed so that you only have to do this once – by integrating your
software with libfprint, you'll be supporting all the fingerprint readers 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 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 therefore hopefully easy to comprehend!), and does its best to hide the

4
doc/libfprint-docs.xml
View file

@ -31,8 +31,8 @@
<xi:include href="xml/drv.xml"/> <xi:include href="xml/drv.xml"/>
<xi:include href="xml/dev.xml"/> <xi:include href="xml/dev.xml"/>
<xi:include href="xml/print_data.xml"/> <xi:include href="xml/print_data.xml"/>
<!-- https://bugs.freedesktop.org/show_bug.cgi?id=106550 <!-- FIXME https://bugs.freedesktop.org/show_bug.cgi?id=106550 -->
<xi:include href="xml/dscv_print.xml"/> --> <xi:include href="xml/dscv_print.xml"/>
<xi:include href="xml/img.xml"/> <xi:include href="xml/img.xml"/>
</part> </part>

16
libfprint/core.c
View file

@ -446,7 +446,7 @@ API_EXPORTED void fp_dscv_devs_free(struct fp_dscv_dev **devs)
* fp_dscv_dev_get_driver: * fp_dscv_dev_get_driver:
* @dev: the discovered device * @dev: the discovered device
* *
* Gets the #fp_driver "driver" for a discovered device. * Gets the #fp_driver for a discovered device.
* *
* Returns: the driver backing the device * Returns: the driver backing the device
*/ */
@ -486,7 +486,7 @@ enum fp_print_data_type fpi_driver_get_data_type(struct fp_driver *drv)
* @dev: the discovered device * @dev: the discovered device
* @print: the print for compatibility checking * @print: the print for compatibility checking
* *
* Determines if a specific #fp_print_data "stored print" appears to be * Determines if a specific #fp_print_data stored print appears to be
* compatible with a discovered device. * compatible with a discovered device.
* *
* Returns: 1 if the print is compatible with the device, 0 otherwise * Returns: 1 if the print is compatible with the device, 0 otherwise
@ -504,7 +504,7 @@ API_EXPORTED int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
* @dev: the discovered device * @dev: the discovered device
* @print: the discovered print for compatibility checking * @print: the discovered print for compatibility checking
* *
* Determines if a specific #fp_dscv_print "discovered print" appears to be * Determines if a specific #fp_dscv_print discovered print appears to be
* compatible with a discovered device. * compatible with a discovered device.
* *
* Returns: 1 if the print is compatible with the device, 0 otherwise * Returns: 1 if the print is compatible with the device, 0 otherwise
@ -522,7 +522,7 @@ API_EXPORTED int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
* @print: the print under inspection * @print: the print under inspection
* *
* Searches a list of discovered devices for a device that appears to be * Searches a list of discovered devices for a device that appears to be
* compatible with a #fp_print_data "stored print". * compatible with a #fp_print_data stored print.
* *
* Returns: the first discovered device that appears to support the print, or * Returns: the first discovered device that appears to support the print, or
* %NULL if no apparently compatible devices could be found * %NULL if no apparently compatible devices could be found
@ -545,7 +545,7 @@ API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev *
* @print: the print under inspection * @print: the print under inspection
* *
* Searches a list of discovered devices for a device that appears to be * Searches a list of discovered devices for a device that appears to be
* compatible with a #fp_dscv_print "discovered print". * compatible with a #fp_dscv_print discovered print.
* *
* Returns: the first discovered device that appears to support the print, or * Returns: the first discovered device that appears to support the print, or
* %NULL if no apparently compatible devices could be found * %NULL if no apparently compatible devices could be found
@ -566,7 +566,7 @@ API_EXPORTED struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev *
* fp_dev_get_driver: * fp_dev_get_driver:
* @dev: the device * @dev: the device
* *
* Get the #fp_driver "driver" for a fingerprint device. * Get the #fp_driver for a fingerprint device.
* *
* Returns: the driver controlling the device * Returns: the driver controlling the device
*/ */
@ -624,7 +624,7 @@ API_EXPORTED int fp_dev_supports_print_data(struct fp_dev *dev,
* @dev: the device * @dev: the device
* @print: the discovered print * @print: the discovered print
* *
* Determines if a #fp_dscv_print "discovered print" appears to be compatible * Determines if a #fp_dscv_print discovered print appears to be compatible
* with a certain device. * with a certain device.
* *
* Returns: 1 if the print is compatible with the device, 0 if not * Returns: 1 if the print is compatible with the device, 0 if not
@ -702,7 +702,7 @@ static struct fp_img_dev *dev_to_img_dev(struct fp_dev *dev)
* Determines if a device has imaging capabilities. If a device has imaging * Determines if a device has imaging capabilities. If a device has imaging
* capabilities you are able to perform imaging operations such as retrieving * capabilities you are able to perform imaging operations such as retrieving
* scan images using fp_dev_img_capture(). However, not all devices are * scan images using fp_dev_img_capture(). However, not all devices are
* imaging devices - some do all processing in hardware. This function will * imaging devices – some do all processing in hardware. This function will
* indicate which class a device in question falls into. * indicate which class a device in question falls into.
* *
* Returns: 1 if the device is an imaging device, 0 if the device does not * Returns: 1 if the device is an imaging device, 0 if the device does not

2
libfprint/data.c
View file

@ -501,7 +501,7 @@ API_EXPORTED int fp_print_data_delete(struct fp_dev *dev,
* be freed with fp_print_data_free() after use. * be freed with fp_print_data_free() after use.
* Attempts to load a stored print based on a #fp_dscv_print * Attempts to load a stored print based on a #fp_dscv_print
* "discovered print" record. * discovered print record.
* *
* A return code of -ENOENT indicates that the file referred to by the * A return code of -ENOENT indicates that the file referred to by the
* discovered print could not be found. Other error codes (both positive and * discovered print could not be found. Other error codes (both positive and

2
libfprint/poll.c
View file

@ -303,7 +303,7 @@ API_EXPORTED int fp_get_next_timeout(struct timeval *tv)
* *
* Retrieve a list of file descriptors that should be polled for events * Retrieve a list of file descriptors that should be polled for events
* interesting to libfprint. This function is only for users who wish to * interesting to libfprint. This function is only for users who wish to
* combine libfprint's file descriptor set with other event sources - more * combine libfprint's file descriptor set with other event sources – more
* simplistic users will be able to call fp_handle_events() or a variant * simplistic users will be able to call fp_handle_events() or a variant
* directly. * directly.
* *

12
libfprint/sync.c
View file

@ -42,7 +42,7 @@ static void sync_open_cb(struct fp_dev *dev, int status, void *user_data)
* @ddev: the discovered device to open * @ddev: the discovered device to open
* *
* Opens and initialises a device. This is the function you call in order * Opens and initialises a device. This is the function you call in order
* to convert a #fp_dscv_dev "discovered device" into an actual device handle * to convert a #fp_dscv_dev discovered device into an actual device handle
* that you can perform operations with. * that you can perform operations with.
* *
* Returns: (transfer none): the opened device handle, or %NULL on error * Returns: (transfer none): the opened device handle, or %NULL on error
@ -154,19 +154,19 @@ static void enroll_stop_cb(struct fp_dev *dev, void *user_data)
* into this function will retry the current stage again. The current stage may * into this function will retry the current stage again. The current stage may
* need to be retried several times. * need to be retried several times.
* *
* The fp_enroll_result#FP_ENROLL_FAIL code may be returned from any enroll * The %FP_ENROLL_FAIL code may be returned from any enroll
* stage. This code indicates that even though the scans themselves have been * stage. This code indicates that even though the scans themselves have been
* acceptable, data processing applied to these scans produces incomprehensible * acceptable, data processing applied to these scans produces incomprehensible
* results. In other words, the user may have been scanning a different finger * results. In other words, the user may have been scanning a different finger
* for each stage or something like that. Like negative error codes, this * for each stage or something like that. Like negative error codes, this
* return code indicates that the enrollment process has been aborted. * return code indicates that the enrollment process has been aborted.
* *
* The fp_enroll_result#FP_ENROLL_PASS code will only ever be returned for * The %FP_ENROLL_PASS code will only ever be returned for
* non-final stages. This return code indicates that the scan was acceptable * non-final stages. This return code indicates that the scan was acceptable
* and the next call into this function will advance onto the next enroll * and the next call into this function will advance onto the next enroll
* stage. * stage.
* *
* The fp_enroll_result#FP_ENROLL_COMPLETE code will only ever be returned * The %FP_ENROLL_COMPLETE code will only ever be returned
* from the final enroll stage. It indicates that enrollment completed * from the final enroll stage. It indicates that enrollment completed
* successfully, and that print_data has been assigned to point to the * successfully, and that print_data has been assigned to point to the
* resultant enrollment data. The print_data parameter will not be modified * resultant enrollment data. The print_data parameter will not be modified
@ -446,7 +446,7 @@ static void identify_stop_cb(struct fp_dev *dev, void *user_data)
* provide images. * provide images.
* *
* This function returns codes from #fp_verify_result. The return code * This function returns codes from #fp_verify_result. The return code
* fp_verify_result#FP_VERIFY_MATCH indicates that the scanned fingerprint * %FP_VERIFY_MATCH indicates that the scanned fingerprint
* does appear in the print gallery, and the match_offset output parameter * does appear in the print gallery, and the match_offset output parameter
* will indicate the index into the print gallery array of the matched print. * will indicate the index into the print gallery array of the matched print.
* *
@ -551,7 +551,7 @@ static void capture_stop_cb(struct fp_dev *dev, void *user_data)
* @img: a location to return the captured image. Must be freed with * @img: a location to return the captured image. Must be freed with
* fp_img_free() after use. * fp_img_free() after use.
* *
* Captures a #fp_img "image" from a device. The returned image is the raw * Captures a #fp_img from a device. The returned image is the raw
* image provided by the device, you may wish to [standardize](libfprint-Image-operations.html#img_std) it. * image provided by the device, you may wish to [standardize](libfprint-Image-operations.html#img_std) it.
* *
* If set, the @unconditional flag indicates that the device should * If set, the @unconditional flag indicates that the device should