doc(event): document network events (#129)

Add extensive documentation to network events to explain the edge-cases.

Co-authored-by: Will <will@cypherpunk.email>

event/network.go

@@ -5,12 +5,51 @@ import (
 	"github.com/libp2p/go-libp2p-core/peer"
 )
 
-// EvtPeerConnectednessChanged should be emitted every time we form a connection with a peer or drop our last
-// connection with the peer. Essentially, it is emitted in two cases:
-// a) We form a/any connection with a peer.
-// b) We go from having a connection/s with a peer to having no connection with the peer.
-// It contains the Id of the remote peer and the new connectedness state.
+// EvtPeerConnectednessChanged should be emitted every time the "connectedness" to a
+// given peer changes. Specifically, this event is emitted in the following
+// cases:
+//
+// * Connectedness = Connected: Every time we transition from having no
+//   connections to a peer to having at least one connection to the peer.
+// * Connectedness = NotConnected: Every time we transition from having at least
+//   one connection to a peer to having no connections to the peer.
+//
+// Additional connectedness states may be added in the future. This list should
+// not be considered exhaustive.
+//
+// Take note:
+//
+//  * It's possible to have _multiple_ connections to a given peer.
+//  * Both libp2p and networks are asynchronous.
+//
+// This means that all of the following situations are possible:
+//
+// A connection is cut and is re-established:
+//
+//   * Peer A observes a transition from Connected -> NotConnected -> Connected
+//   * Peer B observes a transition from Connected -> NotConnected -> Connected
+//
+// Explanation: Both peers observe the connection die. This is the "nice" case.
+//
+// A connection is cut and is re-established.
+//
+//   * Peer A observes a transition from Connected -> NotConnected -> Connected.
+//   * Peer B observes no transition.
+//
+// Explanation: Peer A re-establishes the dead connection. Peer B observes the
+// new connection form before it observes the old connection die.
+//
+// A connection is cut:
+//
+//   * Peer A observes no transition.
+//   * Peer B observes no transition.
+//
+// Explanation: There were two connections and one was cut. This connection
+// might have been in active use but neither peer will observe a change in
+// "connectedness". Peers should always make sure to re-try network requests.
 type EvtPeerConnectednessChanged struct {
-	Peer          peer.ID
+	// Peer is the remote peer who's connectedness has changed.
+	Peer peer.ID
+	// Connectedness is the new connectedness state.
 	Connectedness network.Connectedness
 }