eventbus: minor godoc and interface edits.

event/bus.go

@@ -22,48 +22,54 @@ type Emitter interface {
 	Emit(evt interface{})
 }
 
+// Subscription represents a subscription to one or multiple event types.
 type Subscription interface {
+	io.Closer
+
+	// Out returns the channel from which to consume events.
 	Out() <-chan interface{}
-	Close() error
 }
 
 // Bus is an interface for a type-based event delivery system.
 type Bus interface {
-	// Subscribe creates a new subscription.
+	// Subscribe creates a new Subscription.
+	//
+	// eventType can be either a pointer to a single event type, or a slice of pointers to
+	// subscribe to multiple event types at once, under a single subscription (and channel).
+	//
+	// Failing to drain the channel may cause publishers to block. CancelFunc is guaranteed
+	// to return after last send to the channel.
 	//
-	// EventType must be a pointer to a event type or an array of pointers
+	// Simple example
 	//
-	// Failing to drain the channel may cause publishers to block. CancelFunc must return after
-	// last send to the channel.
+	//  sub, err := eventbus.Subscribe(new(EventType))
+	//  defer sub.Close()
+	//  for e := range sub.Out() {
+	//    event := e.(EventType) // guaranteed safe
+	//    [...]
+	//  }
 	//
-	// Simple Example:
-	// sub, err := eventbus.Subscribe(new(EventType))
-	// defer sub.Close()
-	// for e := range sub.Out() {
-	//   event := e.(EventType) // guaranteed safe
-	//   [...]
-	// }
+	// Multi-type example
 	//
-	// Multi-Type Example:
-	// sub, err := eventbus.Subscribe([]interface{}{new(EventA), new(EventB)})
-	// defer sub.Close()
-	// for e := range sub.Out() {
-	//   select e.(type):
-	//     case EventA:
-	//       [...]
-	//     case EventB:
-	//       [...]
-	//   }
-	// }
+	//  sub, err := eventbus.Subscribe([]interface{}{new(EventA), new(EventB)})
+	//  defer sub.Close()
+	//  for e := range sub.Out() {
+	//    select e.(type):
+	//      case EventA:
+	//        [...]
+	//      case EventB:
+	//        [...]
+	//    }
+	//  }
 	Subscribe(eventType interface{}, opts ...SubscriptionOpt) (Subscription, error)
 
 	// Emitter creates a new event emitter.
 	//
 	// eventType accepts typed nil pointers, and uses the type information for wiring purposes.
 	//
 	// Example:
-	// em, err := eventbus.Emitter(new(EventT))
-	// defer em.Close() // MUST call this after being done with the emitter
-	// em.Emit(EventT{})
+	//  em, err := eventbus.Emitter(new(EventT))
+	//  defer em.Close() // MUST call this after being done with the emitter
+	//  em.Emit(EventT{})
 	Emitter(eventType interface{}, opts ...EmitterOpt) (Emitter, error)
 }