diff --git a/client/config.go b/client/config.go
index 346819d..04b8d2d 100644
--- a/client/config.go
+++ b/client/config.go
@@ -42,12 +42,15 @@ type Config struct {
 	// underlying buffered writer.
 	MaxWriteDelay time.Duration
 
-	// AlwaysAnnounceOnPublish defines when the message callback handler is called.
-	// QOS 0,1: callback always occurs on reception of Publish
-	// QOS 2 and AlwaysAnnounceOnPublish == false: callback occurs on reception of PubRel and returning and error in
-	//   the callback will close the connection before PubComp is sent.
-	// QOS 2 and AlwaysAnnounceOnPublish == true: callback occurs on reception of Publish and returning an error in
-	//   the callback will close the connection, preventing PubRec being sent, thus ensuring redelivery of publish.
+	// AlwaysAnnounceOnPublish defines when the message callback is called.
+	// - QOS 0 and 1: Callback always occurs on reception of Publish.
+	// - QOS 2 and AlwaysAnnounceOnPublish == false: Callback occurs on
+	//   reception of PubRel and returning and error in the callback will close
+	//   the connection before PubComp is sent.
+	// - QOS 2 and AlwaysAnnounceOnPublish == true: Callback occurs on reception
+	//   of Publish and returning an error in the callback will close the
+	//   connection, preventing PubRec being sent, thus ensuring the redelivery
+	//   of Publish.
 	AlwaysAnnounceOnPublish bool
 }
 
diff --git a/client/service.go b/client/service.go
index e29c726..bd75a4e 100644
--- a/client/service.go
+++ b/client/service.go
@@ -37,7 +37,8 @@ type Service struct {
 	// The session used by the client to store unacknowledged packets.
 	Session Session
 
-	// The OnlineCallback is called when the service is connected.
+	// The OnlineCallback is called when the service is connected, but before
+	// topics are resubscribed.
 	//
 	// Note: Execution of the service is resumed after the callback returns.
 	// This means that waiting on a future inside the callback will deadlock the