[libnfc] r1310 committed - libnfc: add modules in documentation.
lib...@googlecode.com
Author: adi...@il4p.fr
Date: Mon Jan 30 03:00:02 2012
Log: libnfc: add modules in documentation.
http://code.google.com/p/libnfc/source/detail?r=1310
Modified:
/trunk/libnfc/nfc.c
=======================================
--- /trunk/libnfc/nfc.c Mon Jan 30 01:43:58 2012
+++ /trunk/libnfc/nfc.c Mon Jan 30 03:00:02 2012
@@ -23,6 +23,40 @@
* @file nfc.c
* @brief NFC library implementation
*/
+/**
+ * @defgroup lib Library initialization/deinitialization
+ * This page details how to initialize and deinitialize libnfc.
Initialization
+ * must be performed before using any libnfc functionality, and similarly
you
+ * must not call any libnfc functions after deinitialization.
+ */
+/**
+ * @defgroup dev NFC Device/Hardware manipulation
+ *
+ */
+/**
+ * @defgroup initiator NFC initiator
+ * act as "reader"
+ */
+/**
+ * @defgroup target NFC target
+ * act as tag (i.e. MIFARE Classic) or NFC target device.
+ */
+/**
+ * @defgroup error Error reporting
+ *
+ */
+/**
+ * @defgroup data Special data accessors
+ *
+ */
+/**
+ * @defgroup properties Properties accessors
+ *
+ */
+/**
+ * @defgroup misc Miscellaneous
+ *
+ */
/* vim:set ts=2 sw=2 et: */
@@ -64,7 +98,7 @@
NULL
};
-/**
+/** \ingroup lib
* @brief Initialize libnfc.
* This function must be called before calling any other libnfc function
* @param context Optional output location for context pointer
@@ -75,7 +109,7 @@
log_init ();
}
-/**
+/** \ingroup lib
* @brief Deinitialize libnfc.
* Should be called after closing all open devices and before your
application terminates.
*@param context The context to deinitialize
@@ -86,7 +120,7 @@
log_fini ();
}
-/**
+/** \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
@@ -119,7 +153,7 @@
return true;
}
-/**
+/** \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
@@ -180,7 +214,7 @@
return NULL;
}
-/**
+/** \ingroup dev
* @brief Close from a NFC device
* @param pnd \a nfc_device struct pointer that represent currently used
device
*
@@ -198,7 +232,7 @@
}
}
-/**
+/** \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.
@@ -228,7 +262,7 @@
return szDeviceFound;
}
-/**
+/** \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
@@ -246,7 +280,7 @@
}
-/**
+/** \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
@@ -264,7 +298,7 @@
HAL (device_set_property_bool, pnd, property, bEnable);
}
-/**
+/** \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
@@ -327,7 +361,7 @@
HAL (initiator_init, pnd);
}
-/**
+/** \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)
*
@@ -370,7 +404,7 @@
HAL (initiator_select_passive_target, pnd, nm, abtInit, szInit, pnt);
}
-/**
+/** \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)
*
@@ -433,7 +467,7 @@
return szTargetFound;
}
-/**
+/** \ingroup initiator
* @brief Polling for NFC targets
* @return Returns polled targets count, otherwise returns libnfc's error
code (negative value).
*
@@ -456,7 +490,7 @@
}
-/**
+/** \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).
*
@@ -480,7 +514,7 @@
HAL (initiator_select_dep_target, pnd, ndm, nbr, pndiInitiator, pnt,
timeout);
}
-/**
+/** \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).
*
@@ -521,7 +555,7 @@
return 0;
}
-/**
+/** \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
@@ -539,7 +573,7 @@
HAL (initiator_deselect_target, pnd);
}
-/**
+/** \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
*
@@ -572,7 +606,7 @@
HAL (initiator_transceive_bytes, pnd, pbtTx, szTx, pbtRx, pszRx, timeout)
}
-/**
+/** \ingroup initiator
* @brief Transceive raw bit-frames to a target
* @return Returns received bits count on success, otherwise returns
libnfc's error code
*
@@ -614,7 +648,7 @@
HAL (initiator_transceive_bits, pnd, pbtTx, szTxBits, pbtTxPar, pbtRx,
pbtRxPar);
}
-/**
+/** \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.
*
@@ -640,7 +674,7 @@
HAL (initiator_transceive_bytes_timed, pnd, pbtTx, szTx, pbtRx, cycles)
}
-/**
+/** \ingroup initiator
* @brief Transceive raw bit-frames to a target
* @return Returns received bits count on success, otherwise returns
libnfc's error code
*
@@ -668,7 +702,7 @@
HAL (initiator_transceive_bits_timed, pnd, pbtTx, szTxBits, pbtTxPar,
pbtRx, pbtRxPar, cycles);
}
-/**
+/** \ingroup target
* @brief Initialize NFC device as an emulated tag
* @return Returns received bytes count on success, otherwise returns
libnfc's error code
*
@@ -729,7 +763,7 @@
HAL (target_init, pnd, pnt, pbtRx, szRx, timeout);
}
-/**
+/** \ingroup dev
* @brief Turn NFC device in idle mode
* @return Returns 0 on success, otherwise returns libnfc's error code.
*
@@ -745,7 +779,7 @@
HAL (idle, pnd);
}
-/**
+/** \ingroup dev
* @brief Abort current running command
* @return Returns 0 on success, otherwise returns libnfc's error code.
*
@@ -762,7 +796,7 @@
HAL (abort_command, pnd);
}
-/**
+/** \ingroup target
* @brief Send bytes and APDU frames
* @return Returns sent bytes count on success, otherwise returns libnfc's
error code
*
@@ -783,7 +817,7 @@
HAL (target_send_bytes, pnd, pbtTx, szTx, timeout);
}
-/**
+/** \ingroup target
* @brief Receive bytes and APDU frames
* @return Returns received bytes count on success, otherwise returns
libnfc's error code
*
@@ -803,7 +837,7 @@
HAL (target_receive_bytes, pnd, pbtRx, szRx, timeout);
}
-/**
+/** \ingroup target
* @brief Send raw bit-frames
* @return Returns sent bits count on success, otherwise returns libnfc's
error code.
*
@@ -820,7 +854,7 @@
HAL (target_send_bits, pnd, pbtTx, szTxBits, pbtTxPar);
}
-/**
+/** \ingroup target
* @brief Receive bit-frames
* @return Returns received bits count on success, otherwise returns
libnfc's error code
*
@@ -861,7 +895,7 @@
{ NFC_ECHIP, "Device's Internal Chip Error" },
};
-/**
+/** \ingroup error
* @brief Return the last error string
* @return Returns a string
*
@@ -882,7 +916,7 @@
return pcRes;
}
-/**
+/** \ingroup error
* @brief Renders the last error in pcStrErrBuf for a maximum size of
szBufLen chars
* @return Returns 0 upon success
*
@@ -894,7 +928,7 @@
return (snprintf (pcStrErrBuf, szBufLen, "%s", nfc_strerror (pnd)) <
0) ? -1 : 0;
}
-/**
+/** \ingroup error
* @brief Display the last error occured on a nfc_device
*
* @param pnd \a nfc_device struct pointer that represent currently used
device
@@ -906,7 +940,7 @@
fprintf (stderr, "%s: %s\n", pcString, nfc_strerror (pnd));
}
-/**
+/** \ingroup error
* @brief Returns last error occured on a nfc_device
* @return Returns an integer that represents to libnfc's error code.
*
@@ -920,7 +954,7 @@
/* Special data accessors */
-/**
+/** \ingroup data
* @brief Returns the device name
* @return Returns a string with the device name
*
@@ -932,7 +966,7 @@
return pnd->name;
}
-/**
+/** \ingroup data
* @brief Returns the device connection string
* @return Returns a string with the device connstring
*
@@ -946,7 +980,7 @@
/* Misc. functions */
-/**
+/** \ingroup misc
* @brief Returns the library version
* @return Returns a string with the library version
*