add modules in documentation.

libnfc/nfc.c

@@ -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 @@ const struct nfc_driver *nfc_drivers[] = {
   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 @@ nfc_init(nfc_context *context)
   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 @@ nfc_exit(nfc_context *context)
   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 @@ nfc_get_default_device (nfc_connstring *connstring)
   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 @@ nfc_open (nfc_context *context, const nfc_connstring connstring)
   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 @@ nfc_close (nfc_device *pnd)
   }
 }
 
-/**
+/** \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 @@ nfc_list_devices (nfc_context *context, nfc_connstring connstrings[] , size_t sz
   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 @@ nfc_device_set_property_int (nfc_device *pnd, const nfc_property property, const
 }
 
 
-/**
+/** \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 @@ nfc_device_set_property_bool (nfc_device *pnd, const nfc_property property, cons
   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 @@ nfc_initiator_init (nfc_device *pnd)
   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 @@ nfc_initiator_select_passive_target (nfc_device *pnd,
   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 @@ nfc_initiator_list_passive_targets (nfc_device *pnd,
   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 @@ nfc_initiator_poll_target (nfc_device *pnd,
 }
 
 
-/**
+/** \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 @@ nfc_initiator_select_dep_target (nfc_device *pnd,
   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 @@ nfc_initiator_poll_dep_target (struct nfc_device *pnd,
   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 @@ nfc_initiator_deselect_target (nfc_device *pnd)
   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 @@ nfc_initiator_transceive_bytes (nfc_device *pnd, const uint8_t *pbtTx, const siz
   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 @@ nfc_initiator_transceive_bits (nfc_device *pnd, const uint8_t *pbtTx, const size
   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 @@ nfc_initiator_transceive_bytes_timed (nfc_device *pnd, const uint8_t *pbtTx, con
   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 @@ nfc_initiator_transceive_bits_timed (nfc_device *pnd, const uint8_t *pbtTx, cons
   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 @@ nfc_target_init (nfc_device *pnd, nfc_target *pnt, uint8_t *pbtRx, const size_t
   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 @@ nfc_idle (nfc_device *pnd)
   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 @@ nfc_abort_command (nfc_device *pnd)
   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 @@ nfc_target_send_bytes (nfc_device *pnd, const uint8_t *pbtTx, const size_t szTx,
   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 @@ nfc_target_receive_bytes (nfc_device *pnd, uint8_t *pbtRx, const size_t szRx, in
   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 @@ nfc_target_send_bits (nfc_device *pnd, const uint8_t *pbtTx, const size_t szTxBi
   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 @@ static struct sErrorMessage {
   { NFC_ECHIP, "Device's Internal Chip Error" },
 };
 
-/**
+/** \ingroup error
  * @brief Return the last error string
  * @return Returns a string
  * 
@@ -882,7 +916,7 @@ nfc_strerror (const nfc_device *pnd)
   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 @@ nfc_strerror_r (const nfc_device *pnd, char *pcStrErrBuf, size_t szBufLen)
   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 @@ nfc_perror (const nfc_device *pnd, const char *pcString)
   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 @@ nfc_device_get_last_error (const nfc_device *pnd)
 
 /* Special data accessors */
 
-/**
+/** \ingroup data
  * @brief Returns the device name
  * @return Returns a string with the device name
  * 
@@ -932,7 +966,7 @@ nfc_device_get_name (nfc_device *pnd)
   return pnd->name;
 }
 
-/**
+/** \ingroup data
  * @brief Returns the device connection string
  * @return Returns a string with the device connstring
  * 
@@ -946,7 +980,7 @@ nfc_device_get_connstring (nfc_device *pnd)
 
 /* Misc. functions */
 
-/**
+/** \ingroup misc
  * @brief Returns the library version
  * @return Returns a string with the library version
  *