diff --git a/doc.go b/doc.go
index fa0d7e1..555285b 100644
--- a/doc.go
+++ b/doc.go
@@ -1,5 +1,3 @@
-package pubsub
-
 // The pubsub package provides facilities for the Publish/Subscribe pattern of message
 // propagation, also known as overlay multicast.
 // The implementation provides topic-based pubsub, with pluggable routing algorithms.
@@ -23,3 +21,4 @@ package pubsub
 //
 // To subscribe to a topic, use `Subscribe`; this will give you a subscription interface
 // from which new messages can be pumped.
+package pubsub
diff --git a/pubsub.go b/pubsub.go
index ebb2dcc..e78b4bc 100644
--- a/pubsub.go
+++ b/pubsub.go
@@ -718,14 +718,16 @@ type addSubReq struct {
 
 type SubOpt func(sub *Subscription) error
 
-// Subscribe returns a new Subscription for the given topic
+// Subscribe returns a new Subscription for the given topic.
+// Note that subscription is not an instanteneous operation. It may take some time
+// before the subscription is processed by the pubsub main loop and propagated to our peers.
 func (p *PubSub) Subscribe(topic string, opts ...SubOpt) (*Subscription, error) {
 	td := pb.TopicDescriptor{Name: &topic}
 
 	return p.SubscribeByTopicDescriptor(&td, opts...)
 }
 
-// SubscribeByTopicDescriptor lets you subscribe a topic using a pb.TopicDescriptor
+// SubscribeByTopicDescriptor lets you subscribe a topic using a pb.TopicDescriptor.
 func (p *PubSub) SubscribeByTopicDescriptor(td *pb.TopicDescriptor, opts ...SubOpt) (*Subscription, error) {
 	if td.GetAuth().GetMode() != pb.TopicDescriptor_AuthOpts_NONE {
 		return nil, fmt.Errorf("auth mode not yet supported")