Mark deprecated endpoints with their replacements

Fixes https://matrix.org/jira/browse/SPEC-415

api/client-server/old_sync.yaml

@@ -20,6 +20,11 @@ paths:
       description: |-
         This will listen for new events and return them to the caller. This will
         block until an event is received, or until the ``timeout`` is reached.
+
+        This endpoint was deprecated in r0 of this specification. Clients
+        should instead call the |/sync|_ API with a ``since`` parameter. See
+        the `migration guide
+        <https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
       security:
         - accessToken: []
       parameters:
@@ -92,6 +97,11 @@ paths:
       description: |-
         This returns the full state for this user, with an optional limit on the
         number of messages per room to return.
+
+        This endpoint was deprecated in r0 of this specification. Clients
+        should instead call the |/sync|_ API with no ``since`` parameter. See
+        the `migration guide
+        <https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
       security:
         - accessToken: []
       parameters:
@@ -373,6 +383,9 @@ paths:
       description: |-
         Get a single event based on ``event_id``. You must have permission to
         retrieve this event e.g. by being a member in the room for this event.
+
+        This endpoint was deprecated in r0 of this specification. Clients
+        should instead call the |/rooms/{roomId}/context/{eventId}|_ API.
       security:
         - accessToken: []
       parameters:

api/client-server/rooms.yaml

@@ -222,6 +222,11 @@ paths:
       summary: Snapshot the current state of a room and its most recent messages.
       description: |-
         Get a copy of the current state and the most recent messages in a room.
+
+        This endpoint was deprecated in r0 of this specification. There is no
+        direct replacement; the relevant information is returned by the
+        |/sync|_ API. See the `migration guide
+        <https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
       security:
         - accessToken: []
       parameters:

specification/client_server_api.rst

@@ -1174,5 +1174,8 @@ have to wait in milliseconds before they can try again.
 .. |/rooms/<room_id>/unban| replace:: ``/rooms/<room_id>/unban``
 .. _/rooms/<room_id>/unban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-unban
 
+.. |/rooms/{roomId}/context/{eventId}| replace:: ``/_matrix/client/unstable/rooms/{roomId}/context/{eventId}``
+.. _/rooms/{roomId}/context/{eventId}: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-context-eventid
+
 .. |/account/3pid| replace:: ``/account/3pid``
 .. _/account/3pid: #post-matrix-client-%CLIENT_MAJOR_VERSION%-account-3pid