diff --git a/syncapi/sync/notifier.go b/syncapi/sync/notifier.go
index 159b7350b..13df3b2ca 100644
--- a/syncapi/sync/notifier.go
+++ b/syncapi/sync/notifier.go
@@ -62,8 +62,8 @@ func NewNotifier(pos types.SyncPosition) *Notifier {
 // Can be called with one among: a *gomatrixserverlib.Event, a room ID, or a list of user IDs.
 // posUpdate contains the latest position(s) for one or more types of events.
 // If a position in posUpdate is 0, it means no updates available of that type.
-// Typically a consumer supplies a posUpdate with and only with the sync position
-// for the type of event it handles to the latest.
+// Typically a consumer supplies a posUpdate with the sync position for the
+// event type it handles set to the latest, leaving other fields as 0.
 func (n *Notifier) OnNewEvent(ev *gomatrixserverlib.Event, roomID string, userIDs []string, posUpdate types.SyncPosition) {
 	// update the current position then notify relevant /sync streams.
 	// This needs to be done PRIOR to waking up users as they will read this value.
diff --git a/syncapi/sync/request.go b/syncapi/sync/request.go
index 371ecd015..2f73dd787 100644
--- a/syncapi/sync/request.go
+++ b/syncapi/sync/request.go
@@ -76,9 +76,9 @@ func getTimeout(timeoutMS string) time.Duration {
 
 // getSyncStreamPosition tries to parse a 'since' token taken from the API to a
 // stream position. If the string is empty then (nil, nil) is returned.
-// There are two types of token: The first is a full length one containing
-// all PDU and EDU positions. The second only contains the PDU position; prev_batch
-// tokens generated by the server will be in this form.
+// There are two forms of tokens: The full length form containing all PDU and EDU
+// positions separated by "_", and the short form containing only the PDU
+// position. Short form can be used for, e.g., `prev_batch` tokens.
 func getSyncStreamPosition(since string) (*types.SyncPosition, error) {
 	if since == "" {
 		return nil, nil
diff --git a/syncapi/types/types.go b/syncapi/types/types.go
index 1ae4b4874..565c00501 100644
--- a/syncapi/types/types.go
+++ b/syncapi/types/types.go
@@ -42,7 +42,8 @@ func (sp SyncPosition) IsAfter(other SyncPosition) bool {
 }
 
 // WithUpdates returns a copy of `sp` with updates represented by `other` applied.
-// If a field is not 0 in `other`, it is considered an update.
+// If a field is not 0 in `other`, it is considered an update and its value
+// will replace the corresponding value in sp.
 func (sp SyncPosition) WithUpdates(other SyncPosition) SyncPosition {
 	ret := sp
 	if other.PDUPosition != 0 {