From b3fe4a1e912a6c53243a3fd994f9cf01178a9523 Mon Sep 17 00:00:00 2001 From: Bastien Nocera Date: Fri, 18 May 2018 05:51:58 +0200 Subject: [PATCH] docs: Update API documentation Fixes to layout, dead links, typography, and more. Thanks to Benjamin Berg for the thorough review --- doc/advanced-topics.xml | 6 +++--- doc/getting-started.xml | 6 +++--- doc/intro.xml | 2 +- doc/libfprint-docs.xml | 4 ++-- libfprint/core.c | 16 ++++++++-------- libfprint/data.c | 2 +- libfprint/poll.c | 2 +- libfprint/sync.c | 12 ++++++------ 8 files changed, 25 insertions(+), 25 deletions(-) diff --git a/doc/advanced-topics.xml b/doc/advanced-topics.xml index bc674573..958d2d53 100644 --- a/doc/advanced-topics.xml +++ b/doc/advanced-topics.xml @@ -60,7 +60,7 @@ 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 + driver ID and devtype of the print in question. Prints are only compatible if the driver ID and 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. @@ -73,7 +73,7 @@ Each driver is assigned a unique ID by the project maintainer. These assignments are - + documented on the wiki and will never change. @@ -93,7 +93,7 @@ Device types - Internally, the \ref drv "driver" behind a device assigns a 32-bit + Internally, the driver behind a device assigns a 32-bit devtype 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. diff --git a/doc/getting-started.xml b/doc/getting-started.xml index 5c2d2080..8ed8592b 100644 --- a/doc/getting-started.xml +++ b/doc/getting-started.xml @@ -6,19 +6,19 @@ Getting Started - libfprint includes several simple functional examples under the examples/ + libfprint includes several simple functional examples under the examples/ directory in the libfprint source distribution. Those are good starting points. 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 device discovery. 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 device operations. This section also details enrollment, image capture, and verification. diff --git a/doc/intro.xml b/doc/intro.xml index cfd91008..5b9e5ece 100644 --- a/doc/intro.xml +++ b/doc/intro.xml @@ -14,7 +14,7 @@ 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 + 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 diff --git a/doc/libfprint-docs.xml b/doc/libfprint-docs.xml index 8a0ff38b..fd674ec4 100644 --- a/doc/libfprint-docs.xml +++ b/doc/libfprint-docs.xml @@ -31,8 +31,8 @@ - + + diff --git a/libfprint/core.c b/libfprint/core.c index e22b3bb5..c2867a09 100644 --- a/libfprint/core.c +++ b/libfprint/core.c @@ -446,7 +446,7 @@ API_EXPORTED void fp_dscv_devs_free(struct fp_dscv_dev **devs) * fp_dscv_dev_get_driver: * @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 */ @@ -486,7 +486,7 @@ enum fp_print_data_type fpi_driver_get_data_type(struct fp_driver *drv) * @dev: the discovered device * @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. * * 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 * @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. * * 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 * * 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 * %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 * * 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 * %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: * @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 */ @@ -624,7 +624,7 @@ API_EXPORTED int fp_dev_supports_print_data(struct fp_dev *dev, * @dev: the device * @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. * * 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 * capabilities you are able to perform imaging operations such as retrieving * 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. * * Returns: 1 if the device is an imaging device, 0 if the device does not diff --git a/libfprint/data.c b/libfprint/data.c index 92fd7be6..a0ac620f 100644 --- a/libfprint/data.c +++ b/libfprint/data.c @@ -501,7 +501,7 @@ API_EXPORTED int fp_print_data_delete(struct fp_dev *dev, * be freed with fp_print_data_free() after use. * 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 * discovered print could not be found. Other error codes (both positive and diff --git a/libfprint/poll.c b/libfprint/poll.c index aad81d16..fca0f7fc 100644 --- a/libfprint/poll.c +++ b/libfprint/poll.c @@ -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 * 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 * directly. * diff --git a/libfprint/sync.c b/libfprint/sync.c index ad1a7946..87c8cb9e 100644 --- a/libfprint/sync.c +++ b/libfprint/sync.c @@ -42,7 +42,7 @@ static void sync_open_cb(struct fp_dev *dev, int status, void *user_data) * @ddev: the discovered device to open * * 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. * * 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 * 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 * acceptable, data processing applied to these scans produces incomprehensible * 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 * 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 * and the next call into this function will advance onto the next enroll * 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 * successfully, and that print_data has been assigned to point to the * 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. * * 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 * 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 * 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. * * If set, the @unconditional flag indicates that the device should