introspection: review comments.

host/host.go

@@ -75,7 +75,13 @@ type Host interface {
 	EventBus() event.Bus
 }
 
-// IntrospectableHost allows a host to act an Introspector
+// IntrospectableHost is implemented by Host implementations that are
+// introspectable, that is, that expose an introspection server.
 type IntrospectableHost interface {
+
+	// Introspector returns the Introspector instance, with which the caller
+	// can:
+	//  - register data providers.
+	//  - fetch introspection data.
 	Introspector() introspect.Introspector
 }

introspect/doc.go

@@ -0,0 +1,9 @@
+// Package introspect is EXPERIMENTAL. It is subject to heavy change, and it
+// WILL change. For now, it is the simplest implementation to power the
+// proof-of-concept of the libp2p introspection framework.
+//
+// Package introspect contains the abstract skeleton of the introspection system
+// of go-libp2p. It holds the introspection data schema, and the primitives that
+// allow subsystems to register data providers, and clients to fetch the current
+// state of the system.
+package introspect

introspect/introspect.go

@@ -1,17 +1,25 @@
 package introspect
 
-// ProtoVersion is the current version of the Proto
+import introspect_pb "github.com/libp2p/go-libp2p-core/introspect/pb"
+
+// ProtoVersion is the current version of the introspection protocol.
 const ProtoVersion uint32 = 1
 
-// Introspector allows other sub-systems/modules to register metrics/data providers AND also
-// enables clients to fetch the current state of the system.
+// EXPERIMENTAL. Introspector allows other sub-systems/modules to register
+// metrics/data providers AND also enables clients to fetch the current state of
+// the system.
 type Introspector interface {
-	// RegisterProviders allows sub-systems/modules to register themselves as data/metrics providers
-	RegisterProviders(p *ProvidersMap) error
 
-	// FetchCurrentState fetches the current state of the sub-systems by calling the providers registered by them on the registry.
-	FetchCurrentState() (*State, error)
+	// EXPERIMENTAL. RegisterDataProviders allows sub-systems/modules to
+	// register callbacks that supply introspection data.
+	RegisterDataProviders(p *DataProviders) error
+
+	// EXPERIMENTAL. FetchFullState returns the full state of the system, by
+	// calling all known data providers and returning a merged cross-cut of the
+	// running system.
+	FetchFullState() (*introspect_pb.State, error)
 
-	// ListenAddress returns the address on which the introspection service will be available
-	ListenAddress() string
+	// EXPERIMENTAL. ListenAddrs returns the addresses on which the
+	// introspection server endpoint is listening for clients.
+	ListenAddrs() []string
 }