docs: Add documentation for enums (#259)

* docs: Add documentation for enums

fix: Add context manager return types

chore: Update gapic-generator-python to v1.8.1
PiperOrigin-RevId: 503210727

Source-Link: googleapis/googleapis@a391fd1

Source-Link: https://github.com/googleapis/googleapis-gen/commit/0080f830dec37c3384157082bce279e37079ea58
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMDA4MGY4MzBkZWMzN2MzMzg0MTU3MDgyYmNlMjc5ZTM3MDc5ZWE1OCJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

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

Author: gcf-owl-bot[bot]

google/cloud/osconfig_v1/services/os_config_service/client.py

@@ -1802,7 +1802,7 @@ def sample_resume_patch_deployment():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "OsConfigServiceClient":
         return self
 
     def __exit__(self, type, value, traceback):

google/cloud/osconfig_v1/services/os_config_zonal_service/client.py

@@ -2179,7 +2179,7 @@ def sample_list_vulnerability_reports():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "OsConfigZonalServiceClient":
         return self
 
     def __exit__(self, type, value, traceback):

google/cloud/osconfig_v1/types/inventory.py

@@ -32,7 +32,18 @@
 
 
 class InventoryView(proto.Enum):
-    r"""The view for inventory objects."""
+    r"""The view for inventory objects.
+
+    Values:
+        INVENTORY_VIEW_UNSPECIFIED (0):
+            The default value.
+            The API defaults to the BASIC view.
+        BASIC (1):
+            Returns the basic inventory information that includes
+            ``os_info``.
+        FULL (2):
+            Returns all fields.
+    """
     INVENTORY_VIEW_UNSPECIFIED = 0
     BASIC = 1
     FULL = 2
@@ -164,12 +175,32 @@ class Item(proto.Message):
         """
 
         class OriginType(proto.Enum):
-            r"""The origin of a specific inventory item."""
+            r"""The origin of a specific inventory item.
+
+            Values:
+                ORIGIN_TYPE_UNSPECIFIED (0):
+                    Invalid. An origin type must be specified.
+                INVENTORY_REPORT (1):
+                    This inventory item was discovered as the
+                    result of the agent reporting inventory via the
+                    reporting API.
+            """
             ORIGIN_TYPE_UNSPECIFIED = 0
             INVENTORY_REPORT = 1
 
         class Type(proto.Enum):
-            r"""The different types of inventory that are tracked on a VM."""
+            r"""The different types of inventory that are tracked on a VM.
+
+            Values:
+                TYPE_UNSPECIFIED (0):
+                    Invalid. An type must be specified.
+                INSTALLED_PACKAGE (1):
+                    This represents a package that is installed
+                    on the VM.
+                AVAILABLE_PACKAGE (2):
+                    This represents an update that is available
+                    for a package.
+            """
             TYPE_UNSPECIFIED = 0
             INSTALLED_PACKAGE = 1
             AVAILABLE_PACKAGE = 2

google/cloud/osconfig_v1/types/os_policy.py

@@ -65,7 +65,22 @@ class OSPolicy(proto.Message):
     """
 
     class Mode(proto.Enum):
-        r"""Policy mode"""
+        r"""Policy mode
+
+        Values:
+            MODE_UNSPECIFIED (0):
+                Invalid mode
+            VALIDATION (1):
+                This mode checks if the configuration
+                resources in the policy are in their desired
+                state. No actions are performed if they are not
+                in the desired state. This mode is used for
+                reporting purposes.
+            ENFORCEMENT (2):
+                This mode checks if the configuration
+                resources in the policy are in their desired
+                state, and if not, enforces the desired state.
+        """
         MODE_UNSPECIFIED = 0
         VALIDATION = 1
         ENFORCEMENT = 2
@@ -288,6 +303,15 @@ class PackageResource(proto.Message):
             class DesiredState(proto.Enum):
                 r"""The desired state that the OS Config agent maintains on the
                 VM.
+
+                Values:
+                    DESIRED_STATE_UNSPECIFIED (0):
+                        Unspecified is invalid.
+                    INSTALLED (1):
+                        Ensure that the package is installed.
+                    REMOVED (2):
+                        The agent ensures that the package is not
+                        installed and uninstalls it if detected.
                 """
                 DESIRED_STATE_UNSPECIFIED = 0
                 INSTALLED = 1
@@ -532,7 +556,18 @@ class AptRepository(proto.Message):
                 """
 
                 class ArchiveType(proto.Enum):
-                    r"""Type of archive."""
+                    r"""Type of archive.
+
+                    Values:
+                        ARCHIVE_TYPE_UNSPECIFIED (0):
+                            Unspecified is invalid.
+                        DEB (1):
+                            Deb indicates that the archive contains
+                            binary files.
+                        DEB_SRC (2):
+                            Deb-src indicates that the archive contains
+                            source files.
+                    """
                     ARCHIVE_TYPE_UNSPECIFIED = 0
                     DEB = 1
                     DEB_SRC = 2
@@ -764,7 +799,24 @@ class Exec(proto.Message):
                 """
 
                 class Interpreter(proto.Enum):
-                    r"""The interpreter to use."""
+                    r"""The interpreter to use.
+
+                    Values:
+                        INTERPRETER_UNSPECIFIED (0):
+                            Invalid value, the request will return
+                            validation error.
+                        NONE (1):
+                            If an interpreter is not specified, the source is executed
+                            directly. This execution, without an interpreter, only
+                            succeeds for executables and scripts that have shebang
+                            lines.
+                        SHELL (2):
+                            Indicates that the script runs with ``/bin/sh`` on Linux and
+                            ``cmd.exe`` on Windows.
+                        POWERSHELL (3):
+                            Indicates that the script runs with
+                            PowerShell.
+                    """
                     INTERPRETER_UNSPECIFIED = 0
                     NONE = 1
                     SHELL = 2
@@ -853,7 +905,20 @@ class FileResource(proto.Message):
             """
 
             class DesiredState(proto.Enum):
-                r"""Desired state of the file."""
+                r"""Desired state of the file.
+
+                Values:
+                    DESIRED_STATE_UNSPECIFIED (0):
+                        Unspecified is invalid.
+                    PRESENT (1):
+                        Ensure file at path is present.
+                    ABSENT (2):
+                        Ensure file at path is absent.
+                    CONTENTS_MATCH (3):
+                        Ensure the contents of the file at path
+                        matches. If the file does not exist it will be
+                        created.
+                """
                 DESIRED_STATE_UNSPECIFIED = 0
                 PRESENT = 1
                 ABSENT = 2

google/cloud/osconfig_v1/types/os_policy_assignment_reports.py

@@ -220,7 +220,23 @@ class OSPolicyCompliance(proto.Message):
         """
 
         class ComplianceState(proto.Enum):
-            r"""Possible compliance states for an os policy."""
+            r"""Possible compliance states for an os policy.
+
+            Values:
+                UNKNOWN (0):
+                    The policy is in an unknown compliance state.
+
+                    Refer to the field ``compliance_state_reason`` to learn the
+                    exact reason for the policy to be in this compliance state.
+                COMPLIANT (1):
+                    Policy is compliant.
+                    The policy is compliant if all the underlying
+                    resources are also compliant.
+                NON_COMPLIANT (2):
+                    Policy is non-compliant.
+                    The policy is non-compliant if one or more
+                    underlying resources are non-compliant.
+            """
             UNKNOWN = 0
             COMPLIANT = 1
             NON_COMPLIANT = 2
@@ -262,7 +278,19 @@ class OSPolicyResourceCompliance(proto.Message):
             """
 
             class ComplianceState(proto.Enum):
-                r"""Possible compliance states for a resource."""
+                r"""Possible compliance states for a resource.
+
+                Values:
+                    UNKNOWN (0):
+                        The resource is in an unknown compliance state.
+
+                        To get more details about why the policy is in this state,
+                        review the output of the ``compliance_state_reason`` field.
+                    COMPLIANT (1):
+                        Resource is compliant.
+                    NON_COMPLIANT (2):
+                        Resource is non-compliant.
+                """
                 UNKNOWN = 0
                 COMPLIANT = 1
                 NON_COMPLIANT = 2
@@ -281,7 +309,30 @@ class OSPolicyResourceConfigStep(proto.Message):
                 """
 
                 class Type(proto.Enum):
-                    r"""Supported configuration step types"""
+                    r"""Supported configuration step types
+
+                    Values:
+                        TYPE_UNSPECIFIED (0):
+                            Default value. This value is unused.
+                        VALIDATION (1):
+                            Checks for resource conflicts such as schema
+                            errors.
+                        DESIRED_STATE_CHECK (2):
+                            Checks the current status of the desired
+                            state for a resource.
+                        DESIRED_STATE_ENFORCEMENT (3):
+                            Enforces the desired state for a resource
+                            that is not in desired state.
+                        DESIRED_STATE_CHECK_POST_ENFORCEMENT (4):
+                            Re-checks the status of the desired state.
+                            This check is done for a resource after the
+                            enforcement of all OS policies.
+                            This step is used to determine the final desired
+                            state status for the resource. It accounts for
+                            any resources that might have drifted from their
+                            desired state due to side effects from executing
+                            other resources.
+                    """
                     TYPE_UNSPECIFIED = 0
                     VALIDATION = 1
                     DESIRED_STATE_CHECK = 2

google/cloud/osconfig_v1/types/os_policy_assignments.py

@@ -119,7 +119,20 @@ class OSPolicyAssignment(proto.Message):
     """
 
     class RolloutState(proto.Enum):
-        r"""OS policy assignment rollout state"""
+        r"""OS policy assignment rollout state
+
+        Values:
+            ROLLOUT_STATE_UNSPECIFIED (0):
+                Invalid value
+            IN_PROGRESS (1):
+                The rollout is in progress.
+            CANCELLING (2):
+                The rollout is being cancelled.
+            CANCELLED (3):
+                The rollout is cancelled.
+            SUCCEEDED (4):
+                The rollout has completed successfully.
+        """
         ROLLOUT_STATE_UNSPECIFIED = 0
         IN_PROGRESS = 1
         CANCELLING = 2
@@ -335,14 +348,38 @@ class OSPolicyAssignmentOperationMetadata(proto.Message):
     """
 
     class APIMethod(proto.Enum):
-        r"""The OS policy assignment API method."""
+        r"""The OS policy assignment API method.
+
+        Values:
+            API_METHOD_UNSPECIFIED (0):
+                Invalid value
+            CREATE (1):
+                Create OS policy assignment API method
+            UPDATE (2):
+                Update OS policy assignment API method
+            DELETE (3):
+                Delete OS policy assignment API method
+        """
         API_METHOD_UNSPECIFIED = 0
         CREATE = 1
         UPDATE = 2
         DELETE = 3
 
     class RolloutState(proto.Enum):
-        r"""State of the rollout"""
+        r"""State of the rollout
+
+        Values:
+            ROLLOUT_STATE_UNSPECIFIED (0):
+                Invalid value
+            IN_PROGRESS (1):
+                The rollout is in progress.
+            CANCELLING (2):
+                The rollout is being cancelled.
+            CANCELLED (3):
+                The rollout is cancelled.
+            SUCCEEDED (4):
+                The rollout has completed successfully.
+        """
         ROLLOUT_STATE_UNSPECIFIED = 0
         IN_PROGRESS = 1
         CANCELLING = 2

google/cloud/osconfig_v1/types/patch_deployments.py

@@ -110,7 +110,20 @@ class PatchDeployment(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Represents state of patch peployment."""
+        r"""Represents state of patch peployment.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                The default value. This value is used if the
+                state is omitted.
+            ACTIVE (1):
+                Active value means that patch deployment
+                generates Patch Jobs.
+            PAUSED (2):
+                Paused value means that patch deployment does
+                not generate Patch jobs. Requires user action to
+                move in and out from this state.
+        """
         STATE_UNSPECIFIED = 0
         ACTIVE = 1
         PAUSED = 2
@@ -239,7 +252,21 @@ class RecurringSchedule(proto.Message):
     """
 
     class Frequency(proto.Enum):
-        r"""Specifies the frequency of the recurring patch deployments."""
+        r"""Specifies the frequency of the recurring patch deployments.
+
+        Values:
+            FREQUENCY_UNSPECIFIED (0):
+                Invalid. A frequency must be specified.
+            WEEKLY (1):
+                Indicates that the frequency of recurrence
+                should be expressed in terms of weeks.
+            MONTHLY (2):
+                Indicates that the frequency of recurrence
+                should be expressed in terms of months.
+            DAILY (3):
+                Indicates that the frequency of recurrence
+                should be expressed in terms of days.
+        """
         FREQUENCY_UNSPECIFIED = 0
         WEEKLY = 1
         MONTHLY = 2