Update some comments and README files.

net/netdev/netdev.h

@@ -159,16 +159,27 @@ FAR struct net_driver_s *netdev_findbyname(FAR const char *ifname);
  * Name: netdev_foreach
  *
  * Description:
- *   Enumerate each registered network device.
+ *   Enumerate each registered network device.  This function will terminate
+ *   when either (1) all devices have been enumerated or (2) when a callback
+ *   returns any non-zero value.
  *
- *   NOTE: netdev semaphore held throughout enumeration.
+ *   NOTE 1:  The network must be locked throughout the enumeration.
+ *   NOTE 2:  No checks are made on devices.  For examples, callbacks will
+ *            will be made on network devices that are in the 'down' state.
+ *            The callback implementations must take into account all
+ *            network device state.  Typically, a network in the down state
+ *            would not terminate the traversal.
  *
  * Input Parameters:
  *   callback - Will be called for each registered device
- *   arg      - User argument passed to callback()
+ *   arg      - Opaque user argument passed to callback()
  *
  * Returned Value:
- *  0:Enumeration completed 1:Enumeration terminated early by callback
+ *  0: Enumeration completed
+ *  1: Enumeration terminated early by callback
+ *
+ * Assumptions:
+ *  The network is locked.
  *
  ****************************************************************************/
 

net/netdev/netdev_foreach.c

@@ -53,16 +53,24 @@
  * Name: netdev_foreach
  *
  * Description:
- *   Enumerate each registered network device.
+ *   Enumerate each registered network device.  This function will terminate
+ *   when either (1) all devices have been enumerated or (2) when a callback
+ *   returns any non-zero value.
  *
- *   NOTE: netdev semaphore held throughout enumeration.
+ *   NOTE 1:  The network must be locked throughout the enumeration.
+ *   NOTE 2:  No checks are made on devices.  For examples, callbacks will
+ *            will be made on network devices that are in the 'down' state.
+ *            The callback implementations must take into account all
+ *            network device state.  Typically, a network in the down state
+ *            would not terminate the traversal.
  *
  * Input Parameters:
  *   callback - Will be called for each registered device
- *   arg      - User argument passed to callback()
+ *   arg      - Opaque user argument passed to callback()
  *
  * Returned Value:
- *  0:Enumeration completed 1:Enumeration terminated early by callback
+ *  0: Enumeration completed
+ *  1: Enumeration terminated early by callback
  *
  * Assumptions:
  *  The network is locked.