[libnfc] r1311 committed - libnfc: add some Doxygen documentation.

[lib...@googlecode.com]

Revision: 1311
Author: adi...@il4p.fr
Date: Tue Jan 31 01:49:43 2012
Log: libnfc: add some Doxygen documentation.
http://code.google.com/p/libnfc/source/detail?r=1311

Modified:
/trunk/examples/doc/quick_start_example1.c
/trunk/examples/nfc-poll.c
/trunk/include/nfc/nfc-emulation.h
/trunk/include/nfc/nfc.h
/trunk/libnfc/additional-pages.dox
/trunk/libnfc/chips/pn53x.c
/trunk/libnfc/chips/pn53x.h
/trunk/libnfc/iso14443-subr.c
/trunk/libnfc/mirror-subr.c
/trunk/libnfc/mirror-subr.h
/trunk/libnfc/nfc-emulation.c
/trunk/libnfc/nfc.c

=======================================
--- /trunk/examples/doc/quick_start_example1.c Wed Jan 25 01:56:05 2012
+++ /trunk/examples/doc/quick_start_example1.c Tue Jan 31 01:49:43 2012
@@ -1,3 +1,8 @@
+/**
+ * @file quick_start_example1.c
+ * @brief Quick start example that presents how to use libnfc
+ */
+
#ifdef HAVE_CONFIG_H
# include "config.h"
#endif // HAVE_CONFIG_H
=======================================
--- /trunk/examples/nfc-poll.c Wed Jan 25 01:56:05 2012
+++ /trunk/examples/nfc-poll.c Tue Jan 31 01:49:43 2012
@@ -29,7 +29,7 @@
*/

/**
- * @file nfc-poll
+ * @file nfc-poll.c
* @brief Polling example
*/

=======================================
--- /trunk/include/nfc/nfc-emulation.h Wed Jan 25 01:56:05 2012
+++ /trunk/include/nfc/nfc-emulation.h Tue Jan 31 01:49:43 2012
@@ -17,6 +17,11 @@
* along with this program. If not, see <http://www.gnu.org/licenses/>
*/

+/**
+ * @file nfc-emulation.h
+ * @brief Provide a small API to ease emulation in libnfc
+ */
+
#ifndef __NFC_EMULATION_H__
#define __NFC_EMULATION_H__

@@ -30,13 +35,20 @@
struct nfc_emulator;
struct nfc_emulation_state_machine;

-
+/**
+ * @struct nfc_emulator
+ * @brief NFC emulator structure
+ */
struct nfc_emulator {
nfc_target *target;
struct nfc_emulation_state_machine *state_machine;
void *user_data;
};

+/**
+ * @struct nfc_emulation_state_machine
+ * @brief NFC emulation state machine structure
+ */
struct nfc_emulation_state_machine {
int (*io)(struct nfc_emulator *emulator, const uint8_t *data_in, const
size_t data_in_len, uint8_t *data_out, const size_t data_out_len);
void *data;
=======================================
--- /trunk/include/nfc/nfc.h Wed Jan 25 01:56:05 2012
+++ /trunk/include/nfc/nfc.h Tue Jan 31 01:49:43 2012
@@ -115,18 +115,67 @@
NFC_EXPORT const char *nfc_version (void);

/* Error codes */
-#define NFC_SUCCESS 0 // No error
-#define NFC_EIO -1 // Input / output error, device will not be usable
anymore
-#define NFC_EINVARG -2 // Invalid argument(s)
-#define NFC_EDEVNOTSUPP -3 // Operation not supported by device
-#define NFC_ENOTSUCHDEV -4 // No such device
-#define NFC_EOVFLOW -5 // Buffer overflow
-#define NFC_ETIMEOUT -6 // Operation timed out
-#define NFC_EOPABORTED -7 // Operation aborted (by user)
-#define NFC_ENOTIMPL -8 // Not (yet) implemented
-#define NFC_ETGRELEASED -10 // Target released
-#define NFC_ERFTRANS -20 // Error while RF transmission
-#define NFC_ECHIP -90 // Device's internal chip error
+/** @ingroup error
+ * @hideinitializer
+ * Success (no error)
+ */
+#define NFC_SUCCESS 0
+/** @ingroup error
+ * @hideinitializer
+ * Input / output error, device will not be usable anymore
+ */
+#define NFC_EIO -1
+/** @ingroup error
+ * @hideinitializer
+ * Invalid argument(s)
+ */
+#define NFC_EINVARG -2
+/** @ingroup error
+ * @hideinitializer
+ * Operation not supported by device
+ */
+#define NFC_EDEVNOTSUPP -3
+/** @ingroup error
+ * @hideinitializer
+ * No such device
+ */
+#define NFC_ENOTSUCHDEV -4
+/** @ingroup error
+ * @hideinitializer
+ * Buffer overflow
+ */
+#define NFC_EOVFLOW -5
+/** @ingroup error
+ * @hideinitializer
+ * Operation timed out
+ */
+#define NFC_ETIMEOUT -6
+/** @ingroup error
+ * @hideinitializer
+ * Operation aborted (by user)
+ */
+#define NFC_EOPABORTED -7
+/** @ingroup error
+ * @hideinitializer
+ * Not (yet) implemented
+ */
+#define NFC_ENOTIMPL -8
+/** @ingroup error
+ * @hideinitializer
+ * Target released
+ */
+#define NFC_ETGRELEASED -10
+/** @ingroup error
+ * @hideinitializer
+ * Error while RF transmission
+ */
+#define NFC_ERFTRANS -20
+/** @ingroup error
+ * @hideinitializer
+ * Device's internal chip error
+ */
+#define NFC_ECHIP -90
+

# ifdef __cplusplus
}
=======================================
--- /trunk/libnfc/additional-pages.dox Wed Sep 8 02:16:24 2010
+++ /trunk/libnfc/additional-pages.dox Tue Jan 31 01:49:43 2012
@@ -3,12 +3,24 @@
*
* @section intro_sec Introduction
* This is the developer manual for \b libnfc.
+ * libnfc is an open source library that allows you to communicate with
NFC devices. For more info, see the
+ * <a href="http://www.libnfc.org">libusb homepage</a>.
*
* @section quick_start_sec Quick start
- * If you are looking for libnfc's public API, you should start with nfc.h
+ * If you are looking for libnfc's public API, you should start with the
Modules page which links to the different categories of libnfc's
functionality.
* Some commented examples that present how to use \b libnfc can be found
here:
* @subpage examples_page
*
+ * Others example programs can be found in the libnfc source distribution
under the "examples" subdirectory.
+ *
+ * You can also find utils in the libnfc source distribution under
the "utils" subdirectory.
+ *
+ * \section errorhandling Error handling
+ *
+ * libusb functions typically return 0 or more on success or a negative
error code
+ * on failure. These negative error codes relate to LIBNFC_ERROR constants
+ * which are listed on the \ref error "Error reporting" documentation page.
+ *
* @section upgrading_sec Upgrading from previous version
* If you are upgrading from a previous \b libnfc version, please take
care about changes, specially API changes.
* All important changes should be listed in @subpage changelog_page.
=======================================
--- /trunk/libnfc/chips/pn53x.c Wed Jan 25 01:56:05 2012
+++ /trunk/libnfc/chips/pn53x.c Tue Jan 31 01:49:43 2012
@@ -20,6 +20,7 @@
*/

/**
+ * @internal
* @file pn53x.c
* @brief PN531, PN532 and PN533 common functions
*/
=======================================
--- /trunk/libnfc/chips/pn53x.h Wed Jan 25 01:56:05 2012
+++ /trunk/libnfc/chips/pn53x.h Tue Jan 31 01:49:43 2012
@@ -114,18 +114,31 @@
# define RFCI_ANALOG_TYPE_B 0x0C // 3
# define RFCI_ANALOG_TYPE_14443_4 0x0D // 9

+/**
+ * @enum pn53x_power_mode
+ * @brief PN53x power mode enumeration
+ */
typedef enum {
NORMAL, // In that case, there is no power saved but the PN53x reacts as
fast as possible on the host controller interface.
POWERDOWN, // Only on PN532, need to be wake up to process commands with
a long preamble
LOWVBAT // Only on PN532, need to be wake up to process commands with a
long preamble and SAMConfiguration command
} pn53x_power_mode;

+/**
+ * @enum pn53x_operating_mode
+ * @brief PN53x operatin mode enumeration
+ */
typedef enum {
IDLE,
INITIATOR,
TARGET,
} pn53x_operating_mode;

+/**
+ * @internal
+ * @struct pn53x_io
+ * @brief PN53x I/O structure
+ */
struct pn53x_io {
int (*send)(struct nfc_device *pnd, const uint8_t *pbtData, const size_t
szData, int timeout);
int (*receive)(struct nfc_device *pnd, uint8_t *pbtData, const size_t
szDataLen, int timeout);
@@ -135,6 +148,12 @@
#define PN53X_CACHE_REGISTER_MIN_ADDRESS PN53X_REG_CIU_Mode
#define PN53X_CACHE_REGISTER_MAX_ADDRESS PN53X_REG_CIU_Coll
#define PN53X_CACHE_REGISTER_SIZE ((PN53X_CACHE_REGISTER_MAX_ADDRESS -
PN53X_CACHE_REGISTER_MIN_ADDRESS) + 1)
+
+/**
+ * @internal
+ * @struct pn53x_data
+ * @brief PN53x data structure
+ */
struct pn53x_data {
/** Chip type (PN531, PN532 or PN533)*/
pn53x_type type;
@@ -174,7 +193,7 @@

/**
* @enum pn53x_modulation
- * @brief NFC modulation
+ * @brief NFC modulation enumeration
*/
typedef enum {
/** Undefined modulation */
@@ -238,6 +257,10 @@
PTT_DEP_ACTIVE_424 = 0x82,
} pn53x_target_type;

+/**
+ * @enum pn532_sam_mode
+ * @brief PN53x SAM mode enumeration
+ */
typedef enum {
PSM_NORMAL = 0x01,
PSM_VIRTUAL_CARD = 0x02,
=======================================
--- /trunk/libnfc/iso14443-subr.c Wed Jan 25 01:56:05 2012
+++ /trunk/libnfc/iso14443-subr.c Tue Jan 31 01:49:43 2012
@@ -19,7 +19,7 @@

/**
* @file iso14443-subr.c
- * @brief
+ * @brief Defines some function extracted for ISO/IEC 14443
*/

#ifdef HAVE_CONFIG_H
@@ -31,6 +31,11 @@

#include <nfc/nfc.h>

+
+/**
+ * @brief CRC
+ *
+ */
void
iso14443a_crc (uint8_t *pbtData, size_t szLen, uint8_t *pbtCrc)
{
@@ -48,12 +53,20 @@
*pbtCrc = (uint8_t) ((wCrc >> 8) & 0xFF);
}

+/**
+ * @brief Append CRC
+ *
+ */
void
iso14443a_crc_append (uint8_t *pbtData, size_t szLen)
{
iso14443a_crc (pbtData, szLen, pbtData + szLen);
}

+/**
+ * @brief Locate historical bytes
+ * @see ISO/IEC 14443-4 (5.2.7 Historical bytes)
+ */
uint8_t *
iso14443a_locate_historical_bytes (uint8_t *pbtAts, size_t szAts, size_t
*pszTk)
{
=======================================
--- /trunk/libnfc/mirror-subr.c Wed Jan 25 01:56:05 2012
+++ /trunk/libnfc/mirror-subr.c Tue Jan 31 01:49:43 2012
@@ -19,7 +19,7 @@

/**
* @file mirror-subr.c
- * @brief
+ * @brief Mirror bytes
*/

#ifdef HAVE_CONFIG_H
=======================================
--- /trunk/libnfc/mirror-subr.h Wed Jan 25 01:56:05 2012
+++ /trunk/libnfc/mirror-subr.h Tue Jan 31 01:49:43 2012
@@ -18,7 +18,7 @@
*
*
* @file mirror-subr.h
- * @brief
+ * @brief Mirror bytes
*/

#ifndef _LIBNFC_MIRROR_SUBR_H_
=======================================
--- /trunk/libnfc/nfc-emulation.c Wed Jan 25 01:56:05 2012
+++ /trunk/libnfc/nfc-emulation.c Tue Jan 31 01:49:43 2012
@@ -18,7 +18,7 @@
*/

/**
- * @file nfc-emulate.c
+ * @file nfc-emulation.c
* @brief Provide a small API to ease emulation in libnfc
*/

=======================================
--- /trunk/libnfc/nfc.c Mon Jan 30 03:00:02 2012
+++ /trunk/libnfc/nfc.c Tue Jan 31 01:49:43 2012
@@ -31,7 +31,10 @@
*/
/**
* @defgroup dev NFC Device/Hardware manipulation
- *
+ * The functionality documented below is designed to help with the
following
+ * operations:
+ * - Enumerating the NFC devices currently attached to the system
+ * - Opening and closing the chosen device
*/
/**
* @defgroup initiator NFC initiator
@@ -98,7 +101,7 @@
NULL
};

-/** \ingroup lib
+/** @ingroup lib
* @brief Initialize libnfc.
* This function must be called before calling any other libnfc function
* @param context Optional output location for context pointer
@@ -109,7 +112,7 @@
log_init ();
}

-/** \ingroup lib
+/** @ingroup lib
* @brief Deinitialize libnfc.
* Should be called after closing all open devices and before your
application terminates.
*@param context The context to deinitialize
@@ -120,7 +123,7 @@
log_fini ();
}

-/** \ingroup dev
+/** @ingroup dev
* @brief Get the defaut NFC device
* @param connstring \a nfc_connstring pointer where the default
connection string will be stored
* @return \e true on success
@@ -153,7 +156,7 @@
return true;
}

-/** \ingroup dev
+/** @ingroup dev
* @brief Open a NFC device
* @param context The context to operate on, or NULL for the default
context.
* @param connstring The device connection string if specific device is
wanted, \c NULL otherwise
@@ -214,7 +217,7 @@
return NULL;
}

-/** \ingroup dev
+/** @ingroup dev
* @brief Close from a NFC device
* @param pnd \a nfc_device struct pointer that represent currently used
device
*
@@ -232,11 +235,11 @@
}
}

-/** \ingroup dev
+/** @ingroup dev
* @brief Probe for discoverable supported devices (ie. only available for
some drivers)
* @return Returns the number of devices found.
* @param context The context to operate on, or NULL for the default
context.
- * @param connstrings The device connection string if specific device is
wanted, \c NULL otherwise
+ * @param connstrings array of \a nfc_connstring.
* @param szDevices size of the \a connstrings array.
*
*/
@@ -262,7 +265,7 @@
return szDeviceFound;
}

-/** \ingroup properties
+/** @ingroup properties
* @brief Set a device's integer-property value
* @return Returns 0 on success, otherwise returns libnfc's error code
(negative value)
* @param pnd \a nfc_device struct pointer that represent currently used
device
@@ -280,7 +283,7 @@
}


-/** \ingroup properties
+/** @ingroup properties
* @brief Set a device's boolean-property value
* @return Returns 0 on success, otherwise returns libnfc's error code
(negative value)
* @param pnd \a nfc_device struct pointer that represent currently used
device
@@ -298,7 +301,7 @@
HAL (device_set_property_bool, pnd, property, bEnable);
}

-/** \ingroup initiator
+/** @ingroup initiator
* @brief Initialize NFC device as initiator (reader)
* @return Returns 0 on success, otherwise returns libnfc's error code
(negative value)
* @param pnd \a nfc_device struct pointer that represent currently used
device
@@ -361,7 +364,7 @@
HAL (initiator_init, pnd);
}

-/** \ingroup initiator
+/** @ingroup initiator
* @brief Select a passive or emulated tag
* @return Returns selected passive target count on success, otherwise
returns libnfc's error code (negative value)
*
@@ -404,7 +407,7 @@
HAL (initiator_select_passive_target, pnd, nm, abtInit, szInit, pnt);
}

-/** \ingroup initiator
+/** @ingroup initiator
* @brief List passive or emulated tags
* @return Returns the number of targets found on success, otherwise
returns libnfc's error code (negative value)
*
@@ -467,12 +470,12 @@
return szTargetFound;
}

-/** \ingroup initiator
+/** @ingroup initiator
* @brief Polling for NFC targets
* @return Returns polled targets count, otherwise returns libnfc's error
code (negative value).
*
* @param pnd \a nfc_device struct pointer that represent currently used
device
- * @param pnmModulations desired modulation
+ * @param pnmModulations desired modulations
* @param szModulations size of \a pnmModulations
* @param uiPollNr specifies the number of polling (0x01 – 0xFE: 1 up to
254 polling, 0xFF: Endless polling)
* @note one polling is a polling for each desired target type
@@ -490,7 +493,7 @@
}


-/** \ingroup initiator
+/** @ingroup initiator
* @brief Select a target and request active or passive mode for D.E.P.
(Data Exchange Protocol)
* @return Returns selected D.E.P targets count on success, otherwise
returns libnfc's error code (negative value).
*
@@ -514,7 +517,7 @@
HAL (initiator_select_dep_target, pnd, ndm, nbr, pndiInitiator, pnt,
timeout);
}

-/** \ingroup initiator
+/** @ingroup initiator
* @brief Poll a target and request active or passive mode for D.E.P.
(Data Exchange Protocol)
* @return Returns selected D.E.P targets count on success, otherwise
returns libnfc's error code (negative value).
*
@@ -555,7 +558,7 @@
return 0;
}

-/** \ingroup initiator
+/** @ingroup initiator
* @brief Deselect a selected passive or emulated tag
* @return Returns 0 on success, otherwise returns libnfc's error code
(negative value).
* @param pnd \a nfc_device struct pointer that represents currently used
device
@@ -573,7 +576,7 @@
HAL (initiator_deselect_target, pnd);
}

-/** \ingroup initiator
+/** @ingroup initiator
* @brief Send data to target then retrieve data from target
* @return Returns received bytes count on success, otherwise returns
libnfc's error code
*
@@ -606,7 +609,7 @@
HAL (initiator_transceive_bytes, pnd, pbtTx, szTx, pbtRx, pszRx, timeout)
}

-/** \ingroup initiator
+/** @ingroup initiator
* @brief Transceive raw bit-frames to a target
* @return Returns received bits count on success, otherwise returns
libnfc's error code
*
@@ -648,7 +651,7 @@
HAL (initiator_transceive_bits, pnd, pbtTx, szTxBits, pbtTxPar, pbtRx,
pbtRxPar);
}

-/** \ingroup initiator
+/** @ingroup initiator
* @brief Send data to target then retrieve data from target
* @return Returns received bytes count on success, otherwise returns
libnfc's error code.
*
@@ -674,7 +677,7 @@
HAL (initiator_transceive_bytes_timed, pnd, pbtTx, szTx, pbtRx, cycles)
}

-/** \ingroup initiator
+/** @ingroup initiator
* @brief Transceive raw bit-frames to a target
* @return Returns received bits count on success, otherwise returns
libnfc's error code
*
@@ -702,7 +705,7 @@
HAL (initiator_transceive_bits_timed, pnd, pbtTx, szTxBits, pbtTxPar,
pbtRx, pbtRxPar, cycles);
}

-/** \ingroup target
+/** @ingroup target
* @brief Initialize NFC device as an emulated tag
* @return Returns received bytes count on success, otherwise returns
libnfc's error code
*
@@ -763,7 +766,7 @@
HAL (target_init, pnd, pnt, pbtRx, szRx, timeout);
}

-/** \ingroup dev
+/** @ingroup dev
* @brief Turn NFC device in idle mode
* @return Returns 0 on success, otherwise returns libnfc's error code.
*
@@ -779,7 +782,7 @@
HAL (idle, pnd);
}

-/** \ingroup dev
+/** @ingroup dev
* @brief Abort current running command
* @return Returns 0 on success, otherwise returns libnfc's error code.
*
@@ -796,7 +799,7 @@
HAL (abort_command, pnd);
}

-/** \ingroup target
+/** @ingroup target
* @brief Send bytes and APDU frames
* @return Returns sent bytes count on success, otherwise returns libnfc's
error code
*
@@ -817,7 +820,7 @@
HAL (target_send_bytes, pnd, pbtTx, szTx, timeout);
}

-/** \ingroup target
+/** @ingroup target
* @brief Receive bytes and APDU frames
* @return Returns received bytes count on success, otherwise returns
libnfc's error code
*
@@ -837,7 +840,7 @@
HAL (target_receive_bytes, pnd, pbtRx, szRx, timeout);
}

-/** \ingroup target
+/** @ingroup target
* @brief Send raw bit-frames
* @return Returns sent bits count on success, otherwise returns libnfc's
error code.
*
@@ -854,7 +857,7 @@
HAL (target_send_bits, pnd, pbtTx, szTxBits, pbtTxPar);
}

-/** \ingroup target
+/** @ingroup target
* @brief Receive bit-frames
* @return Returns received bits count on success, otherwise returns
libnfc's error code
*
@@ -895,7 +898,7 @@
{ NFC_ECHIP, "Device's Internal Chip Error" },
};

-/** \ingroup error
+/** @ingroup error
* @brief Return the last error string
* @return Returns a string
*
@@ -916,7 +919,7 @@
return pcRes;
}

-/** \ingroup error
+/** @ingroup error
* @brief Renders the last error in pcStrErrBuf for a maximum size of
szBufLen chars
* @return Returns 0 upon success
*
@@ -928,7 +931,7 @@
return (snprintf (pcStrErrBuf, szBufLen, "%s", nfc_strerror (pnd)) <
0) ? -1 : 0;
}

-/** \ingroup error
+/** @ingroup error
* @brief Display the last error occured on a nfc_device
*
* @param pnd \a nfc_device struct pointer that represent currently used
device
@@ -940,7 +943,7 @@
fprintf (stderr, "%s: %s\n", pcString, nfc_strerror (pnd));
}

-/** \ingroup error
+/** @ingroup error
* @brief Returns last error occured on a nfc_device
* @return Returns an integer that represents to libnfc's error code.
*
@@ -954,7 +957,7 @@

/* Special data accessors */

-/** \ingroup data
+/** @ingroup data
* @brief Returns the device name
* @return Returns a string with the device name
*
@@ -966,7 +969,7 @@
return pnd->name;
}

-/** \ingroup data
+/** @ingroup data
* @brief Returns the device connection string
* @return Returns a string with the device connstring
*
@@ -980,7 +983,7 @@

/* Misc. functions */

-/** \ingroup misc
+/** @ingroup misc
* @brief Returns the library version
* @return Returns a string with the library version
*