[address-resolver] include age field as part of otEidCacheEntry (#2745)

This commit adds `mAge` field as part of `otEidCacheEntry`. Also
updates comments and fixes minor typo/style issues.

include/openthread/types.h

@@ -974,6 +974,7 @@ typedef struct otEidCacheEntry
 {
     otIp6Address   mTarget;    ///< Target
     otShortAddress mRloc16;    ///< RLOC16
+    uint8_t        mAge;       ///< Age (order of use, 0 indicates most recently used entry)
     bool           mValid : 1; ///< Indicates whether or not the cache entry is valid
 } otEidCacheEntry;
 

src/core/thread/address_resolver.cpp

@@ -73,7 +73,7 @@ AddressResolver::AddressResolver(Instance &aInstance)
     GetNetif().GetIp6().GetIcmp().RegisterHandler(mIcmpHandler);
 }
 
-void AddressResolver::Clear()
+void AddressResolver::Clear(void)
 {
     memset(&mCache, 0, sizeof(mCache));
 
@@ -90,6 +90,7 @@ otError AddressResolver::GetEntry(uint8_t aIndex, otEidCacheEntry &aEntry) const
     VerifyOrExit(aIndex < kCacheEntries, error = OT_ERROR_INVALID_ARGS);
     memcpy(&aEntry.mTarget, &mCache[aIndex].mTarget, sizeof(aEntry.mTarget));
     aEntry.mRloc16 = mCache[aIndex].mRloc16;
+    aEntry.mAge    = mCache[aIndex].mAge;
     aEntry.mValid  = mCache[aIndex].mState == Cache::kStateCached;
 
 exit:

src/core/thread/address_resolver.hpp

@@ -80,10 +80,10 @@ public:
      * This method gets an EID cache entry.
      *
      * @param[in]   aIndex  An index into the EID cache table.
-     * @param[out]  aEntry  A pointer to where the EID information is placed.
+     * @param[out]  aEntry  A reference to where the EID information is placed.
      *
      * @retval OT_ERROR_NONE          Successfully retrieved the EID cache entry.
-     * @retval OT_ERROR_INVALID_ARGS  @p aIndex was out of bounds or @p aEntry was NULL.
+     * @retval OT_ERROR_INVALID_ARGS  @p aIndex was out of bounds.
      *
      */
     otError GetEntry(uint8_t aIndex, otEidCacheEntry &aEntry) const;
@@ -97,7 +97,7 @@ public:
     void Remove(uint16_t aRloc16);
 
     /**
-     * This method removes all EID-to-RLOC cache entries assossiated with a Router ID.
+     * This method removes all EID-to-RLOC cache entries associated with a Router ID.
      *
      * @param[in]  aRouterId  The Router ID.
      *
@@ -121,6 +121,7 @@ public:
      *
      * @retval OT_ERROR_NONE           Successfully provided the RLOC16.
      * @retval OT_ERROR_ADDRESS_QUERY  Initiated an Address Query.
+     * @retval OT_ERROR_DROP           Earlier Address Query for the EID timed out. In retry timeout interval.
      * @retval OT_ERROR_NO_BUFS        Insufficient buffer space available to send Address Query.
      *
      */
@@ -151,6 +152,13 @@ private:
 
     struct Cache
     {
+        enum State
+        {
+            kStateInvalid,
+            kStateQuery,
+            kStateCached,
+        };
+
         Ip6::Address      mTarget;
         uint8_t           mMeshLocalIid[Ip6::Address::kInterfaceIdentifierSize];
         uint32_t          mLastTransactionTime;
@@ -159,14 +167,7 @@ private:
         uint8_t           mTimeout;
         uint8_t           mFailures;
         uint8_t           mAge;
-
-        enum State
-        {
-            kStateInvalid,
-            kStateQuery,
-            kStateCached,
-        };
-        State mState;
+        State             mState;
     };
 
     enum InvalidationReason