Merge pull request #1632 from github/openapi-update-e1e97367acabcef81b3cfc30184974c50a9bc14a7417abde7b12064901b783aa

Update OpenAPI 3.1 Descriptions

Author: dinonuggies1

descriptions-next/api.github.com/api.github.com.json

@@ -6111,7 +6111,7 @@
       },
       "put": {
         "summary": "Mark notifications as read",
-        "description": "Marks all notifications as \"read\" removes it from the [default view on GitHub](https://github.com/notifications). If the number of notifications is too large to complete in one request, you will receive a `202 Accepted` status and GitHub will run an asynchronous process to mark notifications as \"read.\" To check whether any \"unread\" notifications remain, you can use the [List notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user) endpoint and pass the query parameter `all=false`.",
+        "description": "Marks all notifications as \"read\" for the current user. If the number of notifications is too large to complete in one request, you will receive a `202 Accepted` status and GitHub will run an asynchronous process to mark notifications as \"read.\" To check whether any \"unread\" notifications remain, you can use the [List notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user) endpoint and pass the query parameter `all=false`.",
         "tags": [
           "activity"
         ],
@@ -6197,7 +6197,7 @@
     "/notifications/threads/{thread_id}": {
       "get": {
         "summary": "Get a thread",
-        "description": "",
+        "description": "Gets information about a notification thread.",
         "tags": [
           "activity"
         ],
@@ -6246,7 +6246,7 @@
       },
       "patch": {
         "summary": "Mark a thread as read",
-        "description": "",
+        "description": "Marks a thread as \"read.\" Marking a thread as \"read\" is equivalent to clicking a notification in your notification inbox on GitHub: https://github.com/notifications.",
         "tags": [
           "activity"
         ],
@@ -39718,7 +39718,7 @@
     "/repos/{owner}/{repo}/notifications": {
       "get": {
         "summary": "List repository notifications for the authenticated user",
-        "description": "List all notifications for the current user.",
+        "description": "Lists all notifications for the current user in the specified repository.",
         "tags": [
           "activity"
         ],
@@ -39787,7 +39787,7 @@
       },
       "put": {
         "summary": "Mark repository notifications as read",
-        "description": "Marks all notifications in a repository as \"read\" removes them from the [default view on GitHub](https://github.com/notifications). If the number of notifications is too large to complete in one request, you will receive a `202 Accepted` status and GitHub will run an asynchronous process to mark notifications as \"read.\" To check whether any \"unread\" notifications remain, you can use the [List repository notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-repository-notifications-for-the-authenticated-user) endpoint and pass the query parameter `all=false`.",
+        "description": "Marks all notifications in a repository as \"read\" for the current user. If the number of notifications is too large to complete in one request, you will receive a `202 Accepted` status and GitHub will run an asynchronous process to mark notifications as \"read.\" To check whether any \"unread\" notifications remain, you can use the [List repository notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-repository-notifications-for-the-authenticated-user) endpoint and pass the query parameter `all=false`.",
         "tags": [
           "activity"
         ],
@@ -112789,7 +112789,7 @@
       },
       "thread-id": {
         "name": "thread_id",
-        "description": "The unique identifier of the pull request thread.",
+        "description": "The unique identifier of the notification thread. This corresponds to the value returned in the `id` field when you retrieve notifications (for example with the [`GET /notifications` operation](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)).",
         "in": "path",
         "required": true,
         "schema": {

descriptions-next/api.github.com/api.github.com.yaml

@@ -4211,12 +4211,11 @@ paths:
         subcategory: notifications
     put:
       summary: Mark notifications as read
-      description: Marks all notifications as "read" removes it from the [default
-        view on GitHub](https://github.com/notifications). If the number of notifications
-        is too large to complete in one request, you will receive a `202 Accepted`
-        status and GitHub will run an asynchronous process to mark notifications as
-        "read." To check whether any "unread" notifications remain, you can use the
-        [List notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)
+      description: Marks all notifications as "read" for the current user. If the
+        number of notifications is too large to complete in one request, you will
+        receive a `202 Accepted` status and GitHub will run an asynchronous process
+        to mark notifications as "read." To check whether any "unread" notifications
+        remain, you can use the [List notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)
         endpoint and pass the query parameter `all=false`.
       tags:
       - activity
@@ -4277,7 +4276,7 @@ paths:
   "/notifications/threads/{thread_id}":
     get:
       summary: Get a thread
-      description: ''
+      description: Gets information about a notification thread.
       tags:
       - activity
       operationId: activity/get-thread
@@ -4309,7 +4308,8 @@ paths:
         subcategory: notifications
     patch:
       summary: Mark a thread as read
-      description: ''
+      description: 'Marks a thread as "read." Marking a thread as "read" is equivalent
+        to clicking a notification in your notification inbox on GitHub: https://github.com/notifications.'
       tags:
       - activity
       operationId: activity/mark-thread-as-read
@@ -28675,7 +28675,7 @@ paths:
   "/repos/{owner}/{repo}/notifications":
     get:
       summary: List repository notifications for the authenticated user
-      description: List all notifications for the current user.
+      description: Lists all notifications for the current user in the specified repository.
       tags:
       - activity
       operationId: activity/list-repo-notifications-for-authenticated-user
@@ -28713,11 +28713,10 @@ paths:
         subcategory: notifications
     put:
       summary: Mark repository notifications as read
-      description: Marks all notifications in a repository as "read" removes them
-        from the [default view on GitHub](https://github.com/notifications). If the
-        number of notifications is too large to complete in one request, you will
-        receive a `202 Accepted` status and GitHub will run an asynchronous process
-        to mark notifications as "read." To check whether any "unread" notifications
+      description: Marks all notifications in a repository as "read" for the current
+        user. If the number of notifications is too large to complete in one request,
+        you will receive a `202 Accepted` status and GitHub will run an asynchronous
+        process to mark notifications as "read." To check whether any "unread" notifications
         remain, you can use the [List repository notifications for the authenticated
         user](https://docs.github.com/rest/reference/activity#list-repository-notifications-for-the-authenticated-user)
         endpoint and pass the query parameter `all=false`.
@@ -85361,7 +85360,9 @@ components:
         format: date-time
     thread-id:
       name: thread_id
-      description: The unique identifier of the pull request thread.
+      description: The unique identifier of the notification thread. This corresponds
+        to the value returned in the `id` field when you retrieve notifications (for
+        example with the [`GET /notifications` operation](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)).
       in: path
       required: true
       schema:

descriptions-next/api.github.com/dereferenced/api.github.com.deref.json

@@ -54111,7 +54111,7 @@
       },
       "put": {
         "summary": "Mark notifications as read",
-        "description": "Marks all notifications as \"read\" removes it from the [default view on GitHub](https://github.com/notifications). If the number of notifications is too large to complete in one request, you will receive a `202 Accepted` status and GitHub will run an asynchronous process to mark notifications as \"read.\" To check whether any \"unread\" notifications remain, you can use the [List notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user) endpoint and pass the query parameter `all=false`.",
+        "description": "Marks all notifications as \"read\" for the current user. If the number of notifications is too large to complete in one request, you will receive a `202 Accepted` status and GitHub will run an asynchronous process to mark notifications as \"read.\" To check whether any \"unread\" notifications remain, you can use the [List notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user) endpoint and pass the query parameter `all=false`.",
         "tags": [
           "activity"
         ],
@@ -54245,7 +54245,7 @@
     "/notifications/threads/{thread_id}": {
       "get": {
         "summary": "Get a thread",
-        "description": "",
+        "description": "Gets information about a notification thread.",
         "tags": [
           "activity"
         ],
@@ -54257,7 +54257,7 @@
         "parameters": [
           {
             "name": "thread_id",
-            "description": "The unique identifier of the pull request thread.",
+            "description": "The unique identifier of the notification thread. This corresponds to the value returned in the `id` field when you retrieve notifications (for example with the [`GET /notifications` operation](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)).",
             "in": "path",
             "required": true,
             "schema": {
@@ -55237,7 +55237,7 @@
       },
       "patch": {
         "summary": "Mark a thread as read",
-        "description": "",
+        "description": "Marks a thread as \"read.\" Marking a thread as \"read\" is equivalent to clicking a notification in your notification inbox on GitHub: https://github.com/notifications.",
         "tags": [
           "activity"
         ],
@@ -55249,7 +55249,7 @@
         "parameters": [
           {
             "name": "thread_id",
-            "description": "The unique identifier of the pull request thread.",
+            "description": "The unique identifier of the notification thread. This corresponds to the value returned in the `id` field when you retrieve notifications (for example with the [`GET /notifications` operation](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)).",
             "in": "path",
             "required": true,
             "schema": {
@@ -55314,7 +55314,7 @@
         "parameters": [
           {
             "name": "thread_id",
-            "description": "The unique identifier of the pull request thread.",
+            "description": "The unique identifier of the notification thread. This corresponds to the value returned in the `id` field when you retrieve notifications (for example with the [`GET /notifications` operation](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)).",
             "in": "path",
             "required": true,
             "schema": {
@@ -55479,7 +55479,7 @@
         "parameters": [
           {
             "name": "thread_id",
-            "description": "The unique identifier of the pull request thread.",
+            "description": "The unique identifier of the notification thread. This corresponds to the value returned in the `id` field when you retrieve notifications (for example with the [`GET /notifications` operation](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)).",
             "in": "path",
             "required": true,
             "schema": {
@@ -55668,7 +55668,7 @@
         "parameters": [
           {
             "name": "thread_id",
-            "description": "The unique identifier of the pull request thread.",
+            "description": "The unique identifier of the notification thread. This corresponds to the value returned in the `id` field when you retrieve notifications (for example with the [`GET /notifications` operation](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)).",
             "in": "path",
             "required": true,
             "schema": {
@@ -349756,7 +349756,7 @@
     "/repos/{owner}/{repo}/notifications": {
       "get": {
         "summary": "List repository notifications for the authenticated user",
-        "description": "List all notifications for the current user.",
+        "description": "Lists all notifications for the current user in the specified repository.",
         "tags": [
           "activity"
         ],
@@ -350773,7 +350773,7 @@
       },
       "put": {
         "summary": "Mark repository notifications as read",
-        "description": "Marks all notifications in a repository as \"read\" removes them from the [default view on GitHub](https://github.com/notifications). If the number of notifications is too large to complete in one request, you will receive a `202 Accepted` status and GitHub will run an asynchronous process to mark notifications as \"read.\" To check whether any \"unread\" notifications remain, you can use the [List repository notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-repository-notifications-for-the-authenticated-user) endpoint and pass the query parameter `all=false`.",
+        "description": "Marks all notifications in a repository as \"read\" for the current user. If the number of notifications is too large to complete in one request, you will receive a `202 Accepted` status and GitHub will run an asynchronous process to mark notifications as \"read.\" To check whether any \"unread\" notifications remain, you can use the [List repository notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-repository-notifications-for-the-authenticated-user) endpoint and pass the query parameter `all=false`.",
         "tags": [
           "activity"
         ],

descriptions-next/api.github.com/dereferenced/api.github.com.deref.yaml

@@ -13969,12 +13969,11 @@ paths:
         subcategory: notifications
     put:
       summary: Mark notifications as read
-      description: Marks all notifications as "read" removes it from the [default
-        view on GitHub](https://github.com/notifications). If the number of notifications
-        is too large to complete in one request, you will receive a `202 Accepted`
-        status and GitHub will run an asynchronous process to mark notifications as
-        "read." To check whether any "unread" notifications remain, you can use the
-        [List notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)
+      description: Marks all notifications as "read" for the current user. If the
+        number of notifications is too large to complete in one request, you will
+        receive a `202 Accepted` status and GitHub will run an asynchronous process
+        to mark notifications as "read." To check whether any "unread" notifications
+        remain, you can use the [List notifications for the authenticated user](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)
         endpoint and pass the query parameter `all=false`.
       tags:
       - activity
@@ -14034,7 +14033,7 @@ paths:
   "/notifications/threads/{thread_id}":
     get:
       summary: Get a thread
-      description: ''
+      description: Gets information about a notification thread.
       tags:
       - activity
       operationId: activity/get-thread
@@ -14044,7 +14043,9 @@ paths:
       parameters:
       - &91
         name: thread_id
-        description: The unique identifier of the pull request thread.
+        description: The unique identifier of the notification thread. This corresponds
+          to the value returned in the `id` field when you retrieve notifications
+          (for example with the [`GET /notifications` operation](https://docs.github.com/rest/reference/activity#list-notifications-for-the-authenticated-user)).
         in: path
         required: true
         schema:
@@ -14147,7 +14148,8 @@ paths:
         subcategory: notifications
     patch:
       summary: Mark a thread as read
-      description: ''
+      description: 'Marks a thread as "read." Marking a thread as "read" is equivalent
+        to clicking a notification in your notification inbox on GitHub: https://github.com/notifications.'
       tags:
       - activity
       operationId: activity/mark-thread-as-read
@@ -60490,7 +60492,7 @@ paths:
   "/repos/{owner}/{repo}/notifications":
     get:
       summary: List repository notifications for the authenticated user
-      description: List all notifications for the current user.
+      description: Lists all notifications for the current user in the specified repository.
       tags:
       - activity
       operationId: activity/list-repo-notifications-for-authenticated-user
@@ -60525,11 +60527,10 @@ paths:
         subcategory: notifications
     put:
       summary: Mark repository notifications as read
-      description: Marks all notifications in a repository as "read" removes them
-        from the [default view on GitHub](https://github.com/notifications). If the
-        number of notifications is too large to complete in one request, you will
-        receive a `202 Accepted` status and GitHub will run an asynchronous process
-        to mark notifications as "read." To check whether any "unread" notifications
+      description: Marks all notifications in a repository as "read" for the current
+        user. If the number of notifications is too large to complete in one request,
+        you will receive a `202 Accepted` status and GitHub will run an asynchronous
+        process to mark notifications as "read." To check whether any "unread" notifications
         remain, you can use the [List repository notifications for the authenticated
         user](https://docs.github.com/rest/reference/activity#list-repository-notifications-for-the-authenticated-user)
         endpoint and pass the query parameter `all=false`.