docs: [google-apps-chat] update Chat API comments (#12694)

- [ ] Regenerate this pull request now.

PiperOrigin-RevId: 633320855

Source-Link:
googleapis/googleapis@6cac6e4

Source-Link:
googleapis/googleapis-gen@d5f80f5
Copy-Tag:
eyJwIjoicGFja2FnZXMvZ29vZ2xlLWFwcHMtY2hhdC8uT3dsQm90LnlhbWwiLCJoIjoiZDVmODBmNTA2ZGQzYjcyOTdjNWY5MmJjMmRjNzkyYTExYjdmYjM4NyJ9

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
Co-authored-by: Anthonios Partheniou <partheniou@google.com>

Author: gcf-owl-bot[bot]

packages/google-apps-chat/google/apps/chat_v1/services/chat_service/async_client.py

@@ -313,8 +313,9 @@ async def create_message(
         timeout: Union[float, object] = gapic_v1.method.DEFAULT,
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> gc_message.Message:
-        r"""Creates a message in a Google Chat space. For an example, see
-        `Send a
+        r"""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
@@ -769,8 +770,9 @@ async def sample_get_membership():
             name (:class:`str`):
                 Required. 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``
@@ -1572,7 +1574,7 @@ async def sample_get_space():
                 The request object. A request to return a single space.
             name (:class:`str`):
                 Required. Resource name of the space, in the form
-                "spaces/*".
+                `spaces/*`.
 
                 Format: ``spaces/{space}``
 
@@ -1773,19 +1775,19 @@ async def set_up_space(
         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
+        appropriate ``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
@@ -2365,7 +2367,7 @@ async def create_membership(
         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``:
+        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 apps
@@ -2519,8 +2521,12 @@ async def update_membership(
         timeout: Union[float, object] = gapic_v1.method.DEFAULT,
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> gc_membership.Membership:
-        r"""Updates a membership. Requires `user
-        authentication <https://developers.google.com/chat/api/guides/auth/users>`__.
+        r"""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>`__.
 
         .. code-block:: python
 
@@ -3114,7 +3120,9 @@ async def get_space_read_state(
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> space_read_state.SpaceReadState:
         r"""Returns details about a user's read state within a space, used
-        to identify read and unread messages.
+        to identify 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>`__.
@@ -3243,7 +3251,9 @@ async def update_space_read_state(
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> gc_space_read_state.SpaceReadState:
         r"""Updates a user's read state within a space, used to identify
-        read and unread messages.
+        read and 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>`__.
@@ -3394,7 +3404,9 @@ async def get_thread_read_state(
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> thread_read_state.ThreadReadState:
         r"""Returns details about a user's read state within a thread, used
-        to identify read and unread messages.
+        to identify 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>`__.

packages/google-apps-chat/google/apps/chat_v1/services/chat_service/client.py

@@ -859,8 +859,9 @@ def create_message(
         timeout: Union[float, object] = gapic_v1.method.DEFAULT,
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> gc_message.Message:
-        r"""Creates a message in a Google Chat space. For an example, see
-        `Send a
+        r"""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
@@ -1306,8 +1307,9 @@ def sample_get_membership():
             name (str):
                 Required. 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``
@@ -2090,7 +2092,7 @@ def sample_get_space():
                 The request object. A request to return a single space.
             name (str):
                 Required. Resource name of the space, in the form
-                "spaces/*".
+                `spaces/*`.
 
                 Format: ``spaces/{space}``
 
@@ -2285,19 +2287,19 @@ def set_up_space(
         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
+        appropriate ``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
@@ -2865,7 +2867,7 @@ def create_membership(
         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``:
+        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 apps
@@ -3016,8 +3018,12 @@ def update_membership(
         timeout: Union[float, object] = gapic_v1.method.DEFAULT,
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> gc_membership.Membership:
-        r"""Updates a membership. Requires `user
-        authentication <https://developers.google.com/chat/api/guides/auth/users>`__.
+        r"""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>`__.
 
         .. code-block:: python
 
@@ -3596,7 +3602,9 @@ def get_space_read_state(
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> space_read_state.SpaceReadState:
         r"""Returns details about a user's read state within a space, used
-        to identify read and unread messages.
+        to identify 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>`__.
@@ -3722,7 +3730,9 @@ def update_space_read_state(
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> gc_space_read_state.SpaceReadState:
         r"""Updates a user's read state within a space, used to identify
-        read and unread messages.
+        read and 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>`__.
@@ -3870,7 +3880,9 @@ def get_thread_read_state(
         metadata: Sequence[Tuple[str, str]] = (),
     ) -> thread_read_state.ThreadReadState:
         r"""Returns details about a user's read state within a thread, used
-        to identify read and unread messages.
+        to identify 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>`__.

packages/google-apps-chat/google/apps/chat_v1/services/chat_service/transports/grpc.py

@@ -252,8 +252,9 @@ def create_message(
     ) -> Callable[[gc_message.CreateMessageRequest], gc_message.Message]:
         r"""Return a callable for the create message method over gRPC.
 
-        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
@@ -689,19 +690,19 @@ def set_up_space(self) -> Callable[[space_setup.SetUpSpaceRequest], space.Space]
         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
+        appropriate ``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
@@ -906,7 +907,7 @@ def create_membership(
         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``:
+        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 apps
@@ -946,8 +947,12 @@ def update_membership(
     ) -> Callable[[gc_membership.UpdateMembershipRequest], gc_membership.Membership]:
         r"""Return a callable for the update membership method over gRPC.
 
-        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>`__.
 
         Returns:
             Callable[[~.UpdateMembershipRequest],
@@ -1097,7 +1102,9 @@ def get_space_read_state(
         r"""Return a callable for the get space read state method over gRPC.
 
         Returns details about a user's read state within a space, used
-        to identify read and unread messages.
+        to identify 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>`__.
@@ -1130,7 +1137,9 @@ def update_space_read_state(
         r"""Return a callable for the update space read state method over gRPC.
 
         Updates a user's read state within a space, used to identify
-        read and unread messages.
+        read and 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>`__.
@@ -1162,7 +1171,9 @@ def get_thread_read_state(
         r"""Return a callable for the get thread read state method over gRPC.
 
         Returns details about a user's read state within a thread, used
-        to identify read and unread messages.
+        to identify 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>`__.