From d8044a1b07096dff5a29220c174810c22db645bd Mon Sep 17 00:00:00 2001
From: Lauryn Menard <lauryn@zulip.com>
Date: Thu, 30 Nov 2023 19:07:25 +0100
Subject: [PATCH] api-docs: Revise text of /api/test-notify endpoint.

Updates title and main description to follow the general style
of the API endpoint documentation.

Updates `token` description to clarify suggested mobile client
behavior.
---
 zerver/openapi/zulip.yaml | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index bde358019c..681a732c78 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -9523,17 +9523,17 @@ paths:
   /mobile_push/test_notification:
     post:
       operationId: test-notify
-      summary: Sends a test notification to the user's mobile device(s)
+      summary: Send a test notification to mobile device(s)
       tags: ["mobile"]
       description: |
-        This endpoint allows a user to trigger a test push notification to their
-        selected mobile device, or all their mobile devices.
+        Trigger sending a test push notification to the user's
+        selected mobile device or all of their mobile devices.
 
         **Changes**: Starting with Zulip 8.0 (feature level 234), test
         notifications sent via this endpoint use `test` rather than
-        `test-by-device-token` in the `event` field. (All mobile push
-        notifications also now include a `realm_name` field as well as
-        of this feature level).
+        `test-by-device-token` in the `event` field. Also, as of this
+        feature level, all mobile push notifications now include a
+        `realm_name` field.
 
         New in Zulip 8.0 (feature level 217).
       parameters:
@@ -9542,11 +9542,11 @@ paths:
           description: |
             The push token for the device to which to send the test notification.
 
-            If this parameter is not submitted, the test notification will be sent to all of the
-            user's devices registered on the server.
+            If this parameter is not submitted, the test notification will be sent
+            to all of the user's devices registered on the server.
 
-            Mobile device clients should pass this parameter in order to trigger a notification
-            that is only delivered to this client.
+            A mobile client should pass this parameter, to avoid triggering a test
+            notification for other clients.
           schema:
             type: string
           example: "111222"