Clarify how notification counts are calculated in /sync

Fixes https://github.com/matrix-org/matrix-doc/issues/2015

api/client-server/sync.yaml

@@ -167,11 +167,13 @@ paths:
                             this room.
                           allOf:
                           - $ref: "definitions/event_batch.yaml"
-                        "unread_notifications":
+                        unread_notifications:
                           title: Unread Notification Counts
                           type: object
                           description: |-
-                            Counts of unread notifications for this room
+                            Counts of unread notifications for this room. See the
+                            `Receipts module <#module-receipts>`_ for more information
+                            on how these are calculated.
                           properties:
                             highlight_count:
                                 title: Highlighted notification count

changelogs/client_server/newsfragments/2097.clarification

@@ -0,0 +1 @@
+Clarify how ``unread_notifications`` is calculated.

specification/modules/receipts.rst

@@ -26,7 +26,9 @@ to a homeserver. To prevent this from becoming a problem, receipts are implement
 using "up to" markers. This marker indicates that the acknowledgement applies
 to all events "up to and including" the event specified. For example, marking
 an event as "read" would indicate that the user had read all events *up to* the
-referenced event.
+referenced event. Servers MUST decremement the number of pending notifications
+for a user if the events are up to or including the read receipt. This is typically
+done by adjusting the ``unread_notifications`` value in a ``/sync`` response.
 
 Events
 ------