google-cloud-resource_manager-v3 0.3.0 → 0.5.0

data/lib/google/cloud/resource_manager/v3/projects/client.rb

@@ -299,21 +299,23 @@ module Google
             #   the default parameter values, pass an empty Hash as a request object (see above).
             #
             #   @param parent [::String]
-            #     Required. The name of the parent resource to list projects under.
+            #     Required. The name of the parent resource whose projects are being listed.
+            #     Only children of this parent resource are listed; descendants are not
+            #     listed.
             #
-            #     For example, setting this field to 'folders/1234' would list all projects
-            #     directly under that folder.
+            #     If the parent is a folder, use the value `folders/{folder_id}`. If the
+            #     parent is an organization, use the value `organizations/{org_id}`.
             #   @param page_token [::String]
-            #     Optional. A pagination token returned from a previous call to [ListProjects]
-            #     [google.cloud.resourcemanager.v3.Projects.ListProjects]
-            #     that indicates from where listing should continue.
+            #     Optional. A pagination token returned from a previous call to
+            #     [ListProjects] [google.cloud.resourcemanager.v3.Projects.ListProjects] that
+            #     indicates from where listing should continue.
             #   @param page_size [::Integer]
             #     Optional. The maximum number of projects to return in the response.
             #     The server can return fewer projects than requested.
             #     If unspecified, server picks an appropriate default.
             #   @param show_deleted [::Boolean]
-            #     Optional. Indicate that projects in the `DELETE_REQUESTED` state should also be
-            #     returned. Normally only `ACTIVE` projects are returned.
+            #     Optional. Indicate that projects in the `DELETE_REQUESTED` state should
+            #     also be returned. Normally only `ACTIVE` projects are returned.
             #
             # @yield [response, operation] Access the result along with the RPC operation
             # @yieldparam response [::Gapic::PagedEnumerable<::Google::Cloud::ResourceManager::V3::Project>]
@@ -335,13 +337,11 @@ module Google
             #   # Call the list_projects method.
             #   result = client.list_projects request
             #
-            #   # The returned object is of type Gapic::PagedEnumerable. You can
-            #   # iterate over all elements by calling #each, and the enumerable
-            #   # will lazily make API calls to fetch subsequent pages. Other
-            #   # methods are also available for managing paging directly.
-            #   result.each do |response|
+            #   # The returned object is of type Gapic::PagedEnumerable. You can iterate
+            #   # over elements, and API calls will be issued to fetch pages as needed.
+            #   result.each do |item|
             #     # Each element is of type ::Google::Cloud::ResourceManager::V3::Project.
-            #     p response
+            #     p item
             #   end
             #
             def list_projects request, options = nil
@@ -408,22 +408,22 @@ module Google
             #   @param query [::String]
             #     Optional. A query string for searching for projects that the caller has
             #     `resourcemanager.projects.get` permission to. If multiple fields are
-            #     included in the query, the it will return results that match any of the
+            #     included in the query, then it will return results that match any of the
             #     fields. Some eligible fields are:
             #
             #     ```
             #     | Field                   | Description                                  |
             #     |-------------------------|----------------------------------------------|
             #     | displayName, name       | Filters by displayName.                      |
-            #     | parent                  | Project's parent. (for example: folders/123,
-            #     organizations/*) Prefer parent field over parent.type and parent.id. |
-            #     | parent.type             | Parent's type: `folder` or `organization`.   |
-            #     | parent.id               | Parent's id number (for example: 123)        |
-            #     | id, projectId           | Filters by projectId.                        |
-            #     | state, lifecycleState   | Filters by state.                            |
-            #     | labels                  | Filters by label name or value.              |
-            #     | labels.<key> (where *key* is the name of a label) | Filters by label
-            #     name. |
+            #     | parent                  | Project's parent (for example: folders/123,
+            #     organizations/*). Prefer parent field over parent.type and parent.id.| |
+            #     parent.type             | Parent's type: `folder` or `organization`.   | |
+            #     parent.id               | Parent's id number (for example: 123)        | |
+            #     id, projectId           | Filters by projectId.                        | |
+            #     state, lifecycleState   | Filters by state.                            | |
+            #     labels                  | Filters by label name or value.              | |
+            #     labels.\<key\> (where *key* is the name of a label) | Filters by label
+            #     name.|
             #     ```
             #
             #     Search expressions are case insensitive.
@@ -439,16 +439,16 @@ module Google
             #     | NAME:howl        | Equivalent to above.                                |
             #     | labels.color:*   | The project has the label `color`.                  |
             #     | labels.color:red | The project's label `color` has the value `red`.    |
-            #     | labels.color:red&nbsp;labels.size:big | The project's label `color` has
-            #     the value `red` and its label `size` has the value `big`.                |
+            #     | labels.color:red labels.size:big | The project's label `color` has the
+            #     value `red` or its label `size` has the value `big`.                     |
             #     ```
             #
             #     If no query is specified, the call will return projects for which the user
             #     has the `resourcemanager.projects.get` permission.
             #   @param page_token [::String]
-            #     Optional. A pagination token returned from a previous call to [ListProjects]
-            #     [google.cloud.resourcemanager.v3.Projects.ListProjects]
-            #     that indicates from where listing should continue.
+            #     Optional. A pagination token returned from a previous call to
+            #     [ListProjects] [google.cloud.resourcemanager.v3.Projects.ListProjects] that
+            #     indicates from where listing should continue.
             #   @param page_size [::Integer]
             #     Optional. The maximum number of projects to return in the response.
             #     The server can return fewer projects than requested.
@@ -474,13 +474,11 @@ module Google
             #   # Call the search_projects method.
             #   result = client.search_projects request
             #
-            #   # The returned object is of type Gapic::PagedEnumerable. You can
-            #   # iterate over all elements by calling #each, and the enumerable
-            #   # will lazily make API calls to fetch subsequent pages. Other
-            #   # methods are also available for managing paging directly.
-            #   result.each do |response|
+            #   # The returned object is of type Gapic::PagedEnumerable. You can iterate
+            #   # over elements, and API calls will be issued to fetch pages as needed.
+            #   result.each do |item|
             #     # Each element is of type ::Google::Cloud::ResourceManager::V3::Project.
-            #     p response
+            #     p item
             #   end
             #
             def search_projects request, options = nil
@@ -547,7 +545,7 @@ module Google
             #
             #     If the `parent` field is set, the `resourcemanager.projects.create`
             #     permission is checked on the parent resource. If no parent is set and
-            #     the authorization credentials belong to an Organziation, the parent
+            #     the authorization credentials belong to an Organization, the parent
             #     will be set to that Organization.
             #
             # @yield [response, operation] Access the result along with the RPC operation
@@ -570,14 +568,14 @@ module Google
             #   # Call the create_project method.
             #   result = client.create_project request
             #
-            #   # The returned object is of type Gapic::Operation. You can use this
-            #   # object to check the status of an operation, cancel it, or wait
-            #   # for results. Here is how to block until completion:
+            #   # The returned object is of type Gapic::Operation. You can use it to
+            #   # check the status of an operation, cancel it, or wait for results.
+            #   # Here is how to wait for a response.
             #   result.wait_until_done! timeout: 60
             #   if result.response?
             #     p result.response
             #   else
-            #     puts "Error!"
+            #     puts "No response received."
             #   end
             #
             def create_project request, options = nil
@@ -662,14 +660,14 @@ module Google
             #   # Call the update_project method.
             #   result = client.update_project request
             #
-            #   # The returned object is of type Gapic::Operation. You can use this
-            #   # object to check the status of an operation, cancel it, or wait
-            #   # for results. Here is how to block until completion:
+            #   # The returned object is of type Gapic::Operation. You can use it to
+            #   # check the status of an operation, cancel it, or wait for results.
+            #   # Here is how to wait for a response.
             #   result.wait_until_done! timeout: 60
             #   if result.response?
             #     p result.response
             #   else
-            #     puts "Error!"
+            #     puts "No response received."
             #   end
             #
             def update_project request, options = nil
@@ -723,9 +721,12 @@ module Google
             # Upon success, the `Operation.response` field will be populated with the
             # moved project.
             #
-            # The caller must have `resourcemanager.projects.update` permission on the
-            # project and have `resourcemanager.projects.move` permission on the
-            # project's current and proposed new parent.
+            # The caller must have `resourcemanager.projects.move` permission on the
+            # project, on the project's current and proposed new parent.
+            #
+            # If project has no current parent, or it currently does not have an
+            # associated organization resource, you will also need the
+            # `resourcemanager.projects.setIamPolicy` permission in the project.
             #
             # @overload move_project(request, options = nil)
             #   Pass arguments to `move_project` via a request object, either of type
@@ -767,14 +768,14 @@ module Google
             #   # Call the move_project method.
             #   result = client.move_project request
             #
-            #   # The returned object is of type Gapic::Operation. You can use this
-            #   # object to check the status of an operation, cancel it, or wait
-            #   # for results. Here is how to block until completion:
+            #   # The returned object is of type Gapic::Operation. You can use it to
+            #   # check the status of an operation, cancel it, or wait for results.
+            #   # Here is how to wait for a response.
             #   result.wait_until_done! timeout: 60
             #   if result.response?
             #     p result.response
             #   else
-            #     puts "Error!"
+            #     puts "No response received."
             #   end
             #
             def move_project request, options = nil
@@ -828,7 +829,8 @@ module Google
             #
             # This method changes the Project's lifecycle state from
             # {::Google::Cloud::ResourceManager::V3::Project::State::ACTIVE ACTIVE}
-            # to {::Google::Cloud::ResourceManager::V3::Project::State::DELETE_REQUESTED DELETE_REQUESTED}.
+            # to
+            # {::Google::Cloud::ResourceManager::V3::Project::State::DELETE_REQUESTED DELETE_REQUESTED}.
             # The deletion starts at an unspecified time,
             # at which point the Project is no longer accessible.
             #
@@ -891,14 +893,14 @@ module Google
             #   # Call the delete_project method.
             #   result = client.delete_project request
             #
-            #   # The returned object is of type Gapic::Operation. You can use this
-            #   # object to check the status of an operation, cancel it, or wait
-            #   # for results. Here is how to block until completion:
+            #   # The returned object is of type Gapic::Operation. You can use it to
+            #   # check the status of an operation, cancel it, or wait for results.
+            #   # Here is how to wait for a response.
             #   result.wait_until_done! timeout: 60
             #   if result.response?
             #     p result.response
             #   else
-            #     puts "Error!"
+            #     puts "No response received."
             #   end
             #
             def delete_project request, options = nil
@@ -994,14 +996,14 @@ module Google
             #   # Call the undelete_project method.
             #   result = client.undelete_project request
             #
-            #   # The returned object is of type Gapic::Operation. You can use this
-            #   # object to check the status of an operation, cancel it, or wait
-            #   # for results. Here is how to block until completion:
+            #   # The returned object is of type Gapic::Operation. You can use it to
+            #   # check the status of an operation, cancel it, or wait for results.
+            #   # Here is how to wait for a response.
             #   result.wait_until_done! timeout: 60
             #   if result.response?
             #     p result.response
             #   else
-            #     puts "Error!"
+            #     puts "No response received."
             #   end
             #
             def undelete_project request, options = nil
@@ -1047,7 +1049,8 @@ module Google
             end
 
             ##
-            # Returns the IAM access control policy for the specified project.
+            # Returns the IAM access control policy for the specified project, in the
+            # format `projects/{ProjectIdOrNumber}` e.g. projects/123.
             # Permission is denied if the policy or the resource do not exist.
             #
             # @overload get_iam_policy(request, options = nil)
@@ -1137,7 +1140,8 @@ module Google
             end
 
             ##
-            # Sets the IAM access control policy for the specified project.
+            # Sets the IAM access control policy for the specified project, in the
+            # format `projects/{ProjectIdOrNumber}` e.g. projects/123.
             #
             # CAUTION: This method will replace the existing policy, and cannot be used
             # to append additional IAM settings.
@@ -1169,18 +1173,14 @@ module Google
             # `setIamPolicy()`;
             # they must be sent only using the Cloud Platform Console.
             #
-            # + Membership changes that leave the project without any owners that have
-            # accepted the Terms of Service (ToS) will be rejected.
-            #
             # + If the project is not part of an organization, there must be at least
             # one owner who has accepted the Terms of Service (ToS) agreement in the
             # policy. Calling `setIamPolicy()` to remove the last ToS-accepted owner
             # from the policy will fail. This restriction also applies to legacy
             # projects that no longer have owners who have accepted the ToS. Edits to
             # IAM policies will be rejected until the lack of a ToS-accepting owner is
-            # rectified.
-            #
-            # + Calling this method requires enabling the App Engine Admin API.
+            # rectified. If the project is part of an organization, you can remove all
+            # owners, potentially making the organization inaccessible.
             #
             # @overload set_iam_policy(request, options = nil)
             #   Pass arguments to `set_iam_policy` via a request object, either of type
@@ -1277,7 +1277,8 @@ module Google
             end
 
             ##
-            # Returns permissions that a caller has on the specified project.
+            # Returns permissions that a caller has on the specified project, in the
+            # format `projects/{ProjectIdOrNumber}` e.g. projects/123..
             #
             # @overload test_iam_permissions(request, options = nil)
             #   Pass arguments to `test_iam_permissions` via a request object, either of type
@@ -1405,9 +1406,9 @@ module Google
             #    *  (`String`) The path to a service account key file in JSON format
             #    *  (`Hash`) A service account key as a Hash
             #    *  (`Google::Auth::Credentials`) A googleauth credentials object
-            #       (see the [googleauth docs](https://googleapis.dev/ruby/googleauth/latest/index.html))
+            #       (see the [googleauth docs](https://rubydoc.info/gems/googleauth/Google/Auth/Credentials))
             #    *  (`Signet::OAuth2::Client`) A signet oauth2 client object
-            #       (see the [signet docs](https://googleapis.dev/ruby/signet/latest/Signet/OAuth2/Client.html))
+            #       (see the [signet docs](https://rubydoc.info/gems/signet/Signet/OAuth2/Client))
             #    *  (`GRPC::Core::Channel`) a gRPC channel with included credentials
             #    *  (`GRPC::Core::ChannelCredentials`) a gRPC credentails object
             #    *  (`nil`) indicating no credentials

data/lib/google/cloud/resource_manager/v3/projects/operations.rb

@@ -158,13 +158,11 @@ module Google
             #   # Call the list_operations method.
             #   result = client.list_operations request
             #
-            #   # The returned object is of type Gapic::PagedEnumerable. You can
-            #   # iterate over all elements by calling #each, and the enumerable
-            #   # will lazily make API calls to fetch subsequent pages. Other
-            #   # methods are also available for managing paging directly.
-            #   result.each do |response|
+            #   # The returned object is of type Gapic::PagedEnumerable. You can iterate
+            #   # over elements, and API calls will be issued to fetch pages as needed.
+            #   result.each do |item|
             #     # Each element is of type ::Google::Longrunning::Operation.
-            #     p response
+            #     p item
             #   end
             #
             def list_operations request, options = nil
@@ -253,14 +251,14 @@ module Google
             #   # Call the get_operation method.
             #   result = client.get_operation request
             #
-            #   # The returned object is of type Gapic::Operation. You can use this
-            #   # object to check the status of an operation, cancel it, or wait
-            #   # for results. Here is how to block until completion:
+            #   # The returned object is of type Gapic::Operation. You can use it to
+            #   # check the status of an operation, cancel it, or wait for results.
+            #   # Here is how to wait for a response.
             #   result.wait_until_done! timeout: 60
             #   if result.response?
             #     p result.response
             #   else
-            #     puts "Error!"
+            #     puts "No response received."
             #   end
             #
             def get_operation request, options = nil
@@ -540,14 +538,14 @@ module Google
             #   # Call the wait_operation method.
             #   result = client.wait_operation request
             #
-            #   # The returned object is of type Gapic::Operation. You can use this
-            #   # object to check the status of an operation, cancel it, or wait
-            #   # for results. Here is how to block until completion:
+            #   # The returned object is of type Gapic::Operation. You can use it to
+            #   # check the status of an operation, cancel it, or wait for results.
+            #   # Here is how to wait for a response.
             #   result.wait_until_done! timeout: 60
             #   if result.response?
             #     p result.response
             #   else
-            #     puts "Error!"
+            #     puts "No response received."
             #   end
             #
             def wait_operation request, options = nil
@@ -622,9 +620,9 @@ module Google
             #    *  (`String`) The path to a service account key file in JSON format
             #    *  (`Hash`) A service account key as a Hash
             #    *  (`Google::Auth::Credentials`) A googleauth credentials object
-            #       (see the [googleauth docs](https://googleapis.dev/ruby/googleauth/latest/index.html))
+            #       (see the [googleauth docs](https://rubydoc.info/gems/googleauth/Google/Auth/Credentials))
             #    *  (`Signet::OAuth2::Client`) A signet oauth2 client object
-            #       (see the [signet docs](https://googleapis.dev/ruby/signet/latest/Signet/OAuth2/Client.html))
+            #       (see the [signet docs](https://rubydoc.info/gems/signet/Signet/OAuth2/Client))
             #    *  (`GRPC::Core::Channel`) a gRPC channel with included credentials
             #    *  (`GRPC::Core::ChannelCredentials`) a gRPC credentails object
             #    *  (`nil`) indicating no credentials