Update comments: Source Match feature and poll period selection (#1400)

This commit adds/updates comments. It contains no code/logic change.

- Adds comments to describe expected behavior and use of source
  address match feature and the related radio platform functions.

- Updates comments to describe the selection of poll period and the
  `SetAssignPollPeriod()`.

include/openthread/platform/radio.h

@@ -254,15 +254,26 @@ ThreadError otPlatRadioSleep(otInstance *aInstance);
 ThreadError otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel);
 
 /**
- * Enable/Disable source match for AutoPend.
+ * Enable/Disable source address match feature.
+ *
+ * The source address match feature controls how the radio layer decides the "frame pending" bit for acks sent in
+ * response to data request commands from children.
+ *
+ * If disabled, the radio layer must set the "frame pending" on all acks to data request commands.
+ *
+ * If enabled, the radio layer uses the source address match table to determine whether to set or clear the "frame
+ * pending" bit in an ack to a data request command.
+ *
+ * The source address match table provides the list of children for which there is a pending frame. Either a short
+ * address or an extended/long address can be added to the source address match table.
  *
  * @param[in]  aInstance   The OpenThread instance structure.
- * @param[in]  aEnable     Enable/disable source match for automatical pending.
+ * @param[in]  aEnable     Enable/disable source address match feature.
  */
 void otPlatRadioEnableSrcMatch(otInstance *aInstance, bool aEnable);
 
 /**
- * Adding short address to the source match table.
+ * Add a short address to the source address match table.
  *
  * @param[in]  aInstance      The OpenThread instance structure.
  * @param[in]  aShortAddress  The short address to be added.
@@ -273,7 +284,7 @@ void otPlatRadioEnableSrcMatch(otInstance *aInstance, bool aEnable);
 ThreadError otPlatRadioAddSrcMatchShortEntry(otInstance *aInstance, const uint16_t aShortAddress);
 
 /**
- * Adding extended address to the source match table.
+ * Add an extended address to the source address match table.
  *
  * @param[in]  aInstance    The OpenThread instance structure.
  * @param[in]  aExtAddress  The extended address to be added.
@@ -284,29 +295,29 @@ ThreadError otPlatRadioAddSrcMatchShortEntry(otInstance *aInstance, const uint16
 ThreadError otPlatRadioAddSrcMatchExtEntry(otInstance *aInstance, const uint8_t *aExtAddress);
 
 /**
- * Removing short address to the source match table.
+ * Remove a short address from the source address match table.
  *
  * @param[in]  aInstance      The OpenThread instance structure.
  * @param[in]  aShortAddress  The short address to be removed.
  *
  * @retval ::kThreadError_None        Successfully removed short address from the source match table.
- * @retval ::kThreadError_NoAddress   The short address is not in source match table.
+ * @retval ::kThreadError_NoAddress   The short address is not in source address match table.
  */
 ThreadError otPlatRadioClearSrcMatchShortEntry(otInstance *aInstance, const uint16_t aShortAddress);
 
 /**
- * Removing extended address to the source match table of the radio.
+ * Remove an extended address from the source address match table.
  *
  * @param[in]  aInstance    The OpenThread instance structure.
  * @param[in]  aExtAddress  The extended address to be removed.
  *
  * @retval ::kThreadError_None        Successfully removed the extended address from the source match table.
- * @retval ::kThreadError_NoAddress   The extended address is not in source match table.
+ * @retval ::kThreadError_NoAddress   The extended address is not in source address match table.
  */
 ThreadError otPlatRadioClearSrcMatchExtEntry(otInstance *aInstance, const uint8_t *aExtAddress);
 
 /**
- * Removing all the short addresses from the source match table.
+ * Clear all short addresses from the source address match table.
  *
  * @param[in]  aInstance   The OpenThread instance structure.
  *
@@ -314,7 +325,7 @@ ThreadError otPlatRadioClearSrcMatchExtEntry(otInstance *aInstance, const uint8_
 void otPlatRadioClearSrcMatchShortEntries(otInstance *aInstance);
 
 /**
- * Removing all the extended addresses from the source match table.
+ * Clear all the extended/long addresses from source address match table.
  *
  * @param[in]  aInstance   The OpenThread instance structure.
  *

src/core/thread/mesh_forwarder.hpp

@@ -139,15 +139,22 @@ public:
     void SetRxOnWhenIdle(bool aRxOnWhenIdle);
 
     /**
-     * This method sets customized Data Poll period. Only for certification test
+     * This method sets a user-specified Data Poll period.
      *
-     * @param[in]  aPeriod  The Data Poll period in milliseconds.
+     * If the value is set to zero, then the poll interval is managed by the OpenThread stack.
+     * If the user has provided a non-zero poll period, the user value specifies the maximum period between data
+     * request transmissions. Note that OpenThread may send data request transmissions more frequently when expecting
+     * a control-message from a parent.
+     *
+     * Initial/Default value for "assign poll period" is zero.
+     *
+     * @param[in]  aPeriod  The Data Poll period in milliseconds, or zero to mean no user-specified poll period.
      *
      */
     void SetAssignPollPeriod(uint32_t aPeriod);
 
     /**
-     * This method gets the customized Data Poll period. Only for certification test
+     * This method gets the current user-specified Data Poll period.
      *
      * @returns  The Data Poll period in milliseconds.
      *
@@ -155,7 +162,13 @@ public:
     uint32_t GetAssignPollPeriod(void);
 
     /**
-     * This method sets the Data Poll period.
+     *
+     * This method sets the maximum period between data request command transmissions. Note that OpenThread may send
+     * data request transmissions more frequently when expecting a control-message from a parent.
+     *
+     * If the user has provided a non-zero assign poll period (@sa SetAssignPollPeriod), the user value specifies the
+     * maximum period between data request command transmissions and is used in place of @p aPeriod.
+     *
      *
      * @param[in]  aPeriod  The Data Poll period in milliseconds.
      *