consistent documentation

diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h
index a38a7ac69b3074f6f86f2b549e511ef270208e52..8ff9f401e0ecb86e2d486366f2f45fb2d4dd1a05 100644 (file)
--- a/src/include/gnunet_transport_service.h
+++ b/src/include/gnunet_transport_service.h
@@ -608,6 +608,7 @@ GNUNET_TRANSPORT_p2s (enum GNUNET_TRANSPORT_PeerState state);
 int
 GNUNET_TRANSPORT_is_connected (enum GNUNET_TRANSPORT_PeerState state);
 
+
 /**
  * Return information about a specific peer or all peers currently known to
  * transport service once or in monitoring mode. To obtain information about
@@ -623,6 +624,9 @@ GNUNET_TRANSPORT_is_connected (enum GNUNET_TRANSPORT_PeerState state);
  * more time with 'NULL'. After this, the operation must no longer be
  * explicitly canceled.
  *
+ * The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called in the
+ * the peer_callback!
+ *
  * @param cfg configuration to use
  * @param peer a specific peer identity to obtain information for,
  *      NULL for all peers

diff --git a/src/transport/transport_api_monitoring.c b/src/transport/transport_api_monitoring.c
index b753ce73a6b228e14c1f48344363d16ee452a146..92ab2042c3cc58eb2490108c2b9c2da139ab89ca 100644 (file)
--- a/src/transport/transport_api_monitoring.c
+++ b/src/transport/transport_api_monitoring.c
@@ -437,22 +437,29 @@ peer_response_processor (void *cls,
 
 
 /**
- * Return all the known addresses for a specific peer or all peers.
- * Returns continuously all address if one_shot is set to GNUNET_NO
+ * Return information about a specific peer or all peers currently known to
+ * transport service once or in monitoring mode. To obtain information about
+ * a specific peer, a peer identity can be passed. To obtain information about
+ * all peers currently known to transport service, NULL can be passed as peer
+ * identity.
  *
- * CHANGE: Returns the address(es) that we are currently using for this
- * peer.  Upon completion, the 'AddressLookUpCallback' is called one more
- * time with 'NULL' for the address and the peer.  After this, the operation must no
- * longer be explicitly canceled.
+ * For each peer, the callback is called with information about the address used
+ * to communicate with this peer, the state this peer is currently in and the
+ * the current timeout for this state.
+ *
+ * Upon completion, the 'GNUNET_TRANSPORT_PeerIterateCallback' is called one
+ * more time with 'NULL'. After this, the operation must no longer be
+ * explicitly canceled.
  *
  * The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called in the
  * the peer_callback!
  *
  * @param cfg configuration to use
- * @param peer peer identity to look up the addresses of, CHANGE: allow NULL for all (connected) peers
+ * @param peer a specific peer identity to obtain information for,
+ *      NULL for all peers
  * @param one_shot GNUNET_YES to return the current state and then end (with NULL+NULL),
- *                 GNUNET_NO to monitor the set of addresses used (continuously, must be explicitly canceled)
- * @param timeout how long is the lookup allowed to take at most (irrelevant if one_shot is set to GNUNET_NO)
+ *                 GNUNET_NO to monitor peers continuously
+ * @param timeout how long is the lookup allowed to take at most
  * @param peer_callback function to call with the results
  * @param peer_callback_cls closure for peer_address_callback
  */