From: Matthias Wachs <wachs@net.in.tum.de>
Date: Fri, 10 Jan 2014 09:09:58 +0000 (+0000)
Subject: consistent documentation
X-Git-Tag: initial-import-from-subversion-38251~5074
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=c724cd0f9d4c520bfb3f078e1c9a3f12363c7ca7;p=oweals%2Fgnunet.git

consistent documentation
---

diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h
index a38a7ac69..8ff9f401e 100644
--- 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 b753ce73a..92ab2042c 100644
--- 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
  */