Merge pull request #1631 from github/openapi-update-385310cf5995597094388cb13af0925d390eb851849478fed423bdbe69e5d550

Update OpenAPI 3.0 Descriptions

Author: dinonuggies1

descriptions/api.github.com/api.github.com.json

@@ -6069,7 +6069,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"
         ],
@@ -6155,7 +6155,7 @@
     "/notifications/threads/{thread_id}": {
       "get": {
         "summary": "Get a thread",
-        "description": "",
+        "description": "Gets information about a notification thread.",
         "tags": [
           "activity"
         ],
@@ -6204,7 +6204,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"
         ],
@@ -39497,7 +39497,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"
         ],
@@ -39566,7 +39566,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"
         ],
@@ -110008,7 +110008,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/api.github.com/api.github.com.yaml

@@ -4192,12 +4192,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
@@ -4258,7 +4257,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
@@ -4290,7 +4289,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
@@ -28564,7 +28564,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
@@ -28602,11 +28602,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`.
@@ -84835,7 +84834,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/api.github.com/dereferenced/api.github.com.deref.json

@@ -46667,7 +46667,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"
         ],
@@ -46801,7 +46801,7 @@
     "/notifications/threads/{thread_id}": {
       "get": {
         "summary": "Get a thread",
-        "description": "",
+        "description": "Gets information about a notification thread.",
         "tags": [
           "activity"
         ],
@@ -46813,7 +46813,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": {
@@ -47619,7 +47619,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"
         ],
@@ -47631,7 +47631,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": {
@@ -47696,7 +47696,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": {
@@ -47847,7 +47847,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": {
@@ -48022,7 +48022,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": {
@@ -294811,7 +294811,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"
         ],
@@ -295654,7 +295654,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/api.github.com/dereferenced/api.github.com.deref.yaml

@@ -13538,12 +13538,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
@@ -13603,7 +13602,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
@@ -13613,7 +13612,9 @@ paths:
       parameters:
       - &95
         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:
@@ -13716,7 +13717,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
@@ -59100,7 +59102,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
@@ -59135,11 +59137,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`.