Move explanation of notifications to notifications module

api/client-server/sync.yaml

@@ -172,8 +172,8 @@ paths:
                           type: object
                           description: |-
                             Counts of unread notifications for this room. See the
-                            `Receipts module <#module-receipts>`_ for more information
+                            `Receiving notifications section <#receiving-notifications>`_
-                            on how these are calculated.
+                            for more information on how these are calculated.
                           properties:
                             highlight_count:
                                 title: Highlighted notification count

specification/modules/push.rst

@@ -1,4 +1,5 @@
 .. Copyright 2016 OpenMarket Ltd
+.. Copyright 2019 The Matrix.org Foundation C.I.C.
 ..
 .. Licensed under the Apache License, Version 2.0 (the "License");
 .. you may not use this file except in compliance with the License.
@@ -116,6 +117,16 @@ have received.
 
 {{notifications_cs_http_api}}
 
+Receiving notifications
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Servers MUST include the number of unread notifications in a client's ``/sync``
+stream, and MUST update it as it changes. Notifications are determined by the
+push rules which apply to an event.
+
+When the user updates their read receipt (either by using the API or by sending an
+event), notifications prior to and including that event MUST be marked as read.
+
 Push Rules
 ~~~~~~~~~~
 A push rule is a single rule that states under what *conditions* an event should

specification/modules/receipts.rst

@@ -26,9 +26,8 @@ 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. Servers MUST decremement the number of pending notifications
+referenced event. See the `Receiving notifications <#receiving-notifications>`_
-for a user if the events are up to or including the read receipt. This is typically
+section for more information on how read receipts affect notification counts.
-done by adjusting the ``unread_notifications`` value in a ``/sync`` response.
 
 Events
 ------