From 37263c359aea0dedd851df18fd550ecadc8cd894 Mon Sep 17 00:00:00 2001
From: Donatien Garnier <donatien.garnier@arm.com>
Date: Tue, 7 Aug 2018 16:25:17 +0100
Subject: [PATCH] Add doc to NFCController

---
 features/nfc/nfc/NFCController.h | 82 ++++++++++++++++++++++++++++++--
 1 file changed, 79 insertions(+), 3 deletions(-)

diff --git a/features/nfc/nfc/NFCController.h b/features/nfc/nfc/NFCController.h
index 3bdc0a7ba9..8cafebd275 100644
--- a/features/nfc/nfc/NFCController.h
+++ b/features/nfc/nfc/NFCController.h
@@ -29,32 +29,104 @@ namespace nfc {
     class NFCRemoteTarget;
     class NFCControllerDriver;
 
+    /**
+     * @addtogroup nfc
+     * @{
+     */
+
+    /**
+     * This class represents a NFC Controller.
+     * 
+     * A controller can be in one of three different states:
+     *  * Idle/sleep state
+     *  * Discovery state: The controller tries to discover a remote endpoint (initiator or target)
+     *  * Connected state: The controller exchanges data with an endpoint (initiator or target)
+     * 
+     * A NFCController instance needs to be initialized with a NFCControllerDriver instance which abstracts the specific controller being used.
+     * A delegate needs to be set by the user to receive discovery events.
+     */
     class NFCController {
     public:
+
+        /**
+         * The NFCController delegate. Users of the NFCController class need to implement this delegate's methods to receive events.
+         */
         struct Delegate {
+            /**
+             * A enumeration of causes for the discovery process terminating.
+             */
             enum nfc_discovery_terminated_reason_t {
-                nfc_discovery_terminated_completed = 0,
-                nfc_discovery_terminated_canceled,
-                nfc_discovery_terminated_rf_error
+                nfc_discovery_terminated_completed = 0, ///< Process completed, at least one endpoint was discovered
+                nfc_discovery_terminated_canceled, ///< Process was canceled by the user
+                nfc_discovery_terminated_rf_error ///< An unexpected error was encountered during an exchange on the air interface
             };
 
+            /**
+             * The discovery process terminated.
+             * @param[in] reason the cause for the termination
+             */ 
             virtual void on_discovery_terminated(nfc_discovery_terminated_reason_t reason) {}
 
+            /**
+             * A remote initiator was discovered (the local controller is in target mode).
+             * @param[in] the NFCRemoteInitiator instance
+             */
             virtual void on_nfc_initiator_discovered(const NFCRemoteInitiator& nfc_initiator) {}
 
+            /**
+             * A remote target was discovered (the local controller is in initiator mode).
+             * @param[in] the NFCRemoteTarget instance
+             */
             virtual void on_nfc_target_discovered(const NFCRemoteTarget& nfc_target) {}
         };
 
+        /** 
+         * Construct a NFCController instance.
+         *  
+         * @param[in] driver a pointer to a NFCControllerDriver instance
+         * @param[in] queue a pointer to the events queue to use
+         */
         NFCController(NFCControllerDriver* driver, events::EventQueue* queue);
 
+        /** 
+         * Set the delegate that will receive events generated by this controller.
+         * 
+         * @oaram[in] delegate the delegate instance to use
+         */ 
         void set_delegate(Delegate* delegate);
 
+        /**
+         * Get the list of RF protocols supported by this controller.
+         * 
+         * @return a bitmask of RF protocols supported by the controller
+         */
         nfc_rf_protocols_bitmask_t get_supported_rf_protocols() const;
 
+        /**
+         * Set the list of RF protocols to look for during discovery.
+         * 
+         * @param[in] rf_protocols the relevant bitmask
+         * @return NFC_OK on success, or 
+         *  NFC_ERR_UNSUPPORTED if a protocol is not supported by the controller, 
+         *  NFC_ERR_BUSY if the discovery process is already running
+         */ 
         nfc_err_t configure_rf_protocols(nfc_rf_protocols_bitmask_t rf_protocols);
 
+        /**
+         * Start the discovery process using the protocols configured previously.
+         * 
+         * If remote endpoints are connected when this is called, they will be disconnected.
+         * 
+         * @return NFC_OK on success, or 
+         *  NFC_ERR_BUSY if the discovery process is already running
+         */ 
         nfc_err_t start_discovery();
 
+        /**
+         * Cancel/stop a running discovery process.
+         * 
+         * @return NFC_OK
+         */ 
         nfc_err_t cancel_discovery();
 
     private:
@@ -62,6 +134,10 @@ namespace nfc {
         Delegate* _delegate;
     };
 
+    /**
+     * @}
+     */
+
 } // namespace nfc
 } // namespace mbed