docs: update Chat API comments (#7306)

PiperOrigin-RevId: 633320855
Source-Link: googleapis/googleapis@6cac6e4
Source-Link: googleapis/googleapis-gen@d5f80f5
Copy-Tag: eyJwIjoiQXBwc0NoYXQvLk93bEJvdC55YW1sIiwiaCI6ImQ1ZjgwZjUwNmRkM2I3Mjk3YzVmOTJiYzJkYzc5MmExMWI3ZmIzODcifQ==

AppsChat/samples/V1/ChatServiceClient/create_membership.php

@@ -39,8 +39,8 @@
  * directly to the specified space. Requires [user
  * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
  *
- * To specify the member to add, set the `membership.member.name` in the
- * `CreateMembershipRequest`:
+ * To specify the member to add, set the `membership.member.name` for the
+ * human or app member.
  *
  * - To add the calling app to a space or a direct message between two human
  * users, use `users/app`. Unable to add other

AppsChat/samples/V1/ChatServiceClient/create_message.php

@@ -29,7 +29,8 @@
 use Google\Apps\Chat\V1\Message;
 
 /**
- * Creates a message in a Google Chat space. For an example, see [Send a
+ * Creates a message in a Google Chat space. The maximum message size,
+ * including text and cards, is 32,000 bytes. For an example, see [Send a
  * message](https://developers.google.com/workspace/chat/create-messages).
  *
  * Calling this method requires

AppsChat/samples/V1/ChatServiceClient/get_membership.php

@@ -43,8 +43,9 @@
  *
  * @param string $formattedName Resource name of the membership to retrieve.
  *
- *                              To get the app's own membership, you can optionally use
- *                              `spaces/{space}/members/app`.
+ *                              To get the app's own membership [by using user
+ *                              authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user),
+ *                              you can optionally use `spaces/{space}/members/app`.
  *
  *                              Format: `spaces/{space}/members/{member}` or `spaces/{space}/members/app`
  *

AppsChat/samples/V1/ChatServiceClient/get_space_read_state.php

@@ -30,7 +30,9 @@
 
 /**
  * Returns details about a user's read state within a space, used to identify
- * read and unread messages.
+ * read and unread messages. For an example, see [Get details about a user's
+ * space read
+ * state](https://developers.google.com/workspace/chat/get-space-read-state).
  *
  * Requires [user
  * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).

AppsChat/samples/V1/ChatServiceClient/get_thread_read_state.php

@@ -30,7 +30,9 @@
 
 /**
  * Returns details about a user's read state within a thread, used to identify
- * read and unread messages.
+ * read and unread messages. For an example, see [Get details about a user's
+ * thread read
+ * state](https://developers.google.com/workspace/chat/get-thread-read-state).
  *
  * Requires [user
  * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).

AppsChat/samples/V1/ChatServiceClient/list_spaces.php

@@ -46,6 +46,7 @@
  * Lists spaces visible to the caller or authenticated user. Group chats
  * and DMs aren't listed until the first message is sent.
  *
+ *
  * This sample has been automatically generated and should be regarded as a code
  * template only. It will require modifications to work:
  *  - It may require correct/in-range values for request initialization.

AppsChat/samples/V1/ChatServiceClient/set_up_space.php

@@ -36,17 +36,17 @@
  * members](https://developers.google.com/workspace/chat/set-up-spaces).
  *
  * To specify the human members to add, add memberships with the appropriate
- * `member.name` in the `SetUpSpaceRequest`. To add a human user, use
- * `users/{user}`, where `{user}` can be the email address for the user. For
- * users in the same Workspace organization `{user}` can also be the `id` for
- * the person from the People API, or the `id` for the user in the Directory
- * API. For example, if the People API Person profile ID for
- * `user@example.com` is `123456789`, you can add the user to the space by
- * setting the `membership.member.name` to `users/user@example.com` or
- * `users/123456789`.
+ * `membership.member.name`. To add a human user, use `users/{user}`, where
+ * `{user}` can be the email address for the user. For users in the same
+ * Workspace organization `{user}` can also be the `id` for the person from
+ * the People API, or the `id` for the user in the Directory API. For example,
+ * if the People API Person profile ID for `user@example.com` is `123456789`,
+ * you can add the user to the space by setting the `membership.member.name`
+ * to `users/user@example.com` or `users/123456789`.
  *
- * For a space or group chat, if the caller blocks or is blocked by some
- * members, then those members aren't added to the created space.
+ * For a named space or group chat, if the caller blocks, or is blocked
+ * by some members, or doesn't have permission to add some members, then
+ * those members aren't added to the created space.
  *
  * To create a direct message (DM) between the calling user and another human
  * user, specify exactly one membership to represent the human user. If

AppsChat/samples/V1/ChatServiceClient/update_membership.php

@@ -30,8 +30,11 @@
 use Google\Protobuf\FieldMask;
 
 /**
- * Updates a membership. Requires [user
- * authentication](https://developers.google.com/chat/api/guides/auth/users).
+ * Updates a membership. For an example, see [Update a user's membership in
+ * a space](https://developers.google.com/workspace/chat/update-members).
+ *
+ * Requires [user
+ * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
  *
  * This sample has been automatically generated and should be regarded as a code
  * template only. It will require modifications to work:

AppsChat/samples/V1/ChatServiceClient/update_space_read_state.php

@@ -31,7 +31,8 @@
 
 /**
  * Updates a user's read state within a space, used to identify read and
- * unread messages.
+ * unread messages. For an example, see [Update a user's space read
+ * state](https://developers.google.com/workspace/chat/update-space-read-state).
  *
  * Requires [user
  * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).

AppsChat/src/Chat/V1/Client/ChatServiceClient.php

@@ -482,8 +482,8 @@ public function completeImportSpace(
      * directly to the specified space. Requires [user
      * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
      *
-     * To specify the member to add, set the `membership.member.name` in the
-     * `CreateMembershipRequest`:
+     * To specify the member to add, set the `membership.member.name` for the
+     * human or app member.
      *
      * - To add the calling app to a space or a direct message between two human
      * users, use `users/app`. Unable to add other
@@ -521,7 +521,8 @@ public function createMembership(CreateMembershipRequest $request, array $callOp
     }
 
     /**
-     * Creates a message in a Google Chat space. For an example, see [Send a
+     * Creates a message in a Google Chat space. The maximum message size,
+     * including text and cards, is 32,000 bytes. For an example, see [Send a
      * message](https://developers.google.com/workspace/chat/create-messages).
      *
      * Calling this method requires
@@ -938,7 +939,9 @@ public function getSpace(GetSpaceRequest $request, array $callOptions = []): Spa
 
     /**
      * Returns details about a user's read state within a space, used to identify
-     * read and unread messages.
+     * read and unread messages. For an example, see [Get details about a user's
+     * space read
+     * state](https://developers.google.com/workspace/chat/get-space-read-state).
      *
      * Requires [user
      * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
@@ -968,7 +971,9 @@ public function getSpaceReadState(GetSpaceReadStateRequest $request, array $call
 
     /**
      * Returns details about a user's read state within a thread, used to identify
-     * read and unread messages.
+     * read and unread messages. For an example, see [Get details about a user's
+     * thread read
+     * state](https://developers.google.com/workspace/chat/get-thread-read-state).
      *
      * Requires [user
      * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
@@ -1117,6 +1122,7 @@ public function listReactions(ListReactionsRequest $request, array $callOptions
      * Lists spaces visible to the caller or authenticated user. Group chats
      * and DMs aren't listed until the first message is sent.
      *
+     *
      * The async variant is {@see ChatServiceClient::listSpacesAsync()} .
      *
      * @example samples/V1/ChatServiceClient/list_spaces.php
@@ -1148,17 +1154,17 @@ public function listSpaces(ListSpacesRequest $request, array $callOptions = []):
      * members](https://developers.google.com/workspace/chat/set-up-spaces).
      *
      * To specify the human members to add, add memberships with the appropriate
-     * `member.name` in the `SetUpSpaceRequest`. To add a human user, use
-     * `users/{user}`, where `{user}` can be the email address for the user. For
-     * users in the same Workspace organization `{user}` can also be the `id` for
-     * the person from the People API, or the `id` for the user in the Directory
-     * API. For example, if the People API Person profile ID for
-     * `user@example.com` is `123456789`, you can add the user to the space by
-     * setting the `membership.member.name` to `users/user@example.com` or
-     * `users/123456789`.
-     *
-     * For a space or group chat, if the caller blocks or is blocked by some
-     * members, then those members aren't added to the created space.
+     * `membership.member.name`. To add a human user, use `users/{user}`, where
+     * `{user}` can be the email address for the user. For users in the same
+     * Workspace organization `{user}` can also be the `id` for the person from
+     * the People API, or the `id` for the user in the Directory API. For example,
+     * if the People API Person profile ID for `user@example.com` is `123456789`,
+     * you can add the user to the space by setting the `membership.member.name`
+     * to `users/user@example.com` or `users/123456789`.
+     *
+     * For a named space or group chat, if the caller blocks, or is blocked
+     * by some members, or doesn't have permission to add some members, then
+     * those members aren't added to the created space.
      *
      * To create a direct message (DM) between the calling user and another human
      * user, specify exactly one membership to represent the human user. If
@@ -1207,8 +1213,11 @@ public function setUpSpace(SetUpSpaceRequest $request, array $callOptions = []):
     }
 
     /**
-     * Updates a membership. Requires [user
-     * authentication](https://developers.google.com/chat/api/guides/auth/users).
+     * Updates a membership. For an example, see [Update a user's membership in
+     * a space](https://developers.google.com/workspace/chat/update-members).
+     *
+     * Requires [user
+     * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
      *
      * The async variant is {@see ChatServiceClient::updateMembershipAsync()} .
      *
@@ -1311,7 +1320,8 @@ public function updateSpace(UpdateSpaceRequest $request, array $callOptions = []
 
     /**
      * Updates a user's read state within a space, used to identify read and
-     * unread messages.
+     * unread messages. For an example, see [Update a user's space read
+     * state](https://developers.google.com/workspace/chat/update-space-read-state).
      *
      * Requires [user
      * authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).