Add doc for NFCEEPROMDriver and amend API slightly

features/nfc/nfc/NFCEEPROM.h

@@ -42,7 +42,7 @@ namespace nfc {
      * by the NFC Forum, therefore encoding NDEF data in these EEPROMs will 
      * ensure that it is understandable by a NFC reader.
      */ 
-    class NFCEEPROM : public NFCTarget {
+    class NFCEEPROM : public NFCTarget, public NFCEEPROMDriver::Delegate {
     public:
         /** 
          * Construct a NFCEEPROM instance.
@@ -50,7 +50,7 @@ namespace nfc {
          * @param[in] driver a pointer to a NFCEEPROMDriver instance
          */  
         NFCEEPROM(NFCEEPROMDriver* driver);
-        
+
         virtual ~NFCTarget();
 
         /**
@@ -65,6 +65,15 @@ namespace nfc {
          * @oaram[in] delegate the delegate instance to use
          */ 
         void set_delegate(Delegate* delegate);
+
+    private:
+        // Implementation of NFCEEPROMDriver::Delegate
+        virtual void has_started_session(bool success);
+        virtual void has_read_bytes(bool success);
+        virtual void has_written_bytes(bool success);
+        virtual void has_set_size(bool success);
+        virtual void has_gotten_size(bool success, size_t size);
+        virtual void has_erased_bytes(bool success);
     };
 
     /**

features/nfc/nfc/NFCEEPROMDriver.h

@@ -26,29 +26,149 @@
 namespace mbed {
 namespace nfc {
 
+    /**
+     * @addtogroup nfc
+     * @{
+     */
+    
+    /**
+     * The abstraction for a NFC EEPROM driver.
+     * Implementers need to derive from this class and implement its methods.
+     */ 
     class NFCEEPROMDriver  {
     public:
+        /**
+         * Construct a NFCEEPROM driver instance.
+         */
         NFCEEPROMDriver();
         
+        /**
+         * The NFCEEPROMDriver delegate.
+         * Methods in this class are called by the driver on completion of long-running operations.
+         */
         struct Delegate {
+            /**
+             * Completion of session start operation.
+             * 
+             * @param[in] success whether this operation succeeded
+             */  
             virtual void has_started_session(bool success) = 0;
-            virtual void has_read_bytes(bool success, const uint8_t* bytes) = 0;
+
+            /**
+             * Completion of session end operation.
+             * 
+             * @param[in] success whether this operation succeeded
+             */  
+            virtual void has_ended_session(bool success) = 0;
+
+            /**
+             * Completion of read operation.
+             * 
+             * @param[in] success whether this operation succeeded
+             */  
+            virtual void has_read_bytes(bool success) = 0;
+
+            /**
+             * Completion of write operation.
+             * 
+             * @param[in] success whether this operation succeeded
+             */  
             virtual void has_written_bytes(bool success) = 0;
+
+            /**
+             * Completion of size setting operation.
+             * 
+             * @param[in] success whether this operation succeeded
+             */  
             virtual void has_set_size(bool success) = 0;
+
+            /**
+             * Completion of size retrieval operation.
+             * 
+             * @param[in] success whether this operation succeeded
+             * @param[out] the current addressable memory size
+             */  
             virtual void has_gotten_size(bool success, size_t size) = 0;
+
+            /**
+             * Completion of erasing operation.
+             * 
+             * @param[in] success whether this operation succeeded
+             */  
             virtual void has_erased_bytes(bool success) = 0;
         };
 
+        /** 
+         * Set the delegate that will receive events generated by this EEPROM.
+         * 
+         * @oaram[in] delegate the delegate instance to use
+         */ 
         void set_delegate(Delegate* delegate);
 
+        /** 
+         * Reset and initialize the EEPROM.
+         * This method should complete synchronously.
+         */ 
         virtual void reset() = 0;
+
+        /**
+         * Get the maximum memory size addressable by the EEPROM.
+         */ 
         virtual size_t get_max_size() = 0;
+
+        /**
+         * Start a session of operations (reads, writes, erases, size gets/sets).
+         * This method is called prior to any memory access to allow the underlying implementation 
+         * to disable the RF interface or abort the transaction if it's being used. 
+         * This method should complete asynchronously by calling has_started_session().
+         */ 
         virtual void start_session() = 0; // This could lock the chip's RF interface
+
+        /**
+         * End a session.
+         * This method should complete asynchronously by calling has_ended_session().
+         */ 
         virtual void end_session() = 0;
-        virtual void read_bytes(uint32_t address, size_t count) = 0;
+
+        /**
+         * Read bytes from memory.
+         * @param[in] address the virtual address (starting from 0) from which to start the read.
+         * @param[out] bytes a buffer in which the read bytes will be stored.
+         *  This buffer should remain valid till the callback is called.
+         * @oaram[in] count the number of bytes to read.
+         * This method should complete asynchronously by calling has_read_bytes().
+         */ 
+        virtual void read_bytes(uint32_t address, uint8_t* bytes, size_t count) = 0;
+
+        /**
+         * Write bytes to memory.
+         * @param[in] address the virtual address (starting from 0) from which to start the write.
+         * @param[in] bytes a buffer from to copy.
+         *  This buffer should remain valid till the callback is called.
+         * @oaram[in] count the number of bytes to write.
+         * This method should complete asynchronously by calling has_written_bytes().
+         */ 
         virtual void write_bytes(uint32_t address, const uint8_t* bytes, size_t count) = 0;
+
+        /**
+         * Set the size of the addressable memory.
+         * @oaram[in] count the number of addressable bytes.
+         * This method should complete asynchronously by calling has_set_size().
+         */ 
         virtual void set_size(size_t count) = 0;
+
+        /**
+         * Get the size of the addressable memory.
+         * This method should complete asynchronously by calling has_gotten_size().
+         */ 
         virtual void get_size() = 0;
+
+        /**
+         * Erase bytes from memory.
+         * @param[in] address the virtual address (starting from 0) from which to start erasing.
+         * @oaram[in] count the number of bytes to erase.
+         * This method should complete asynchronously by calling has_erased_bytes().
+         */ 
         virtual void erase_bytes(uint32_t address, size_t size) = 0;
 
     protected:  
@@ -58,6 +178,10 @@ namespace nfc {
         Delegate* _delegate;
     };
 
+    /**
+     * @}
+     */
+
 } // namespace nfc
 } // namespace mbed