docs: Add documentation for enums (#228)

* 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: googleapis/googleapis-gen@0080f83
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>

packages/grafeas/grafeas/grafeas_v1/services/grafeas/client.py

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

packages/grafeas/grafeas/grafeas_v1/types/common.py

@@ -34,7 +34,38 @@
 
 
 class NoteKind(proto.Enum):
-    r"""Kind represents the kinds of notes supported."""
+    r"""Kind represents the kinds of notes supported.
+
+    Values:
+        NOTE_KIND_UNSPECIFIED (0):
+            Default value. This value is unused.
+        VULNERABILITY (1):
+            The note and occurrence represent a package
+            vulnerability.
+        BUILD (2):
+            The note and occurrence assert build
+            provenance.
+        IMAGE (3):
+            This represents an image basis relationship.
+        PACKAGE (4):
+            This represents a package installed via a
+            package manager.
+        DEPLOYMENT (5):
+            The note and occurrence track deployment
+            events.
+        DISCOVERY (6):
+            The note and occurrence track the initial
+            discovery status of a resource.
+        ATTESTATION (7):
+            This represents a logical "role" that can
+            attest to artifacts.
+        UPGRADE (8):
+            This represents an available package upgrade.
+        COMPLIANCE (9):
+            This represents a Compliance Note
+        DSSE_ATTESTATION (10):
+            This represents a DSSE attestation Note
+    """
     NOTE_KIND_UNSPECIFIED = 0
     VULNERABILITY = 1
     BUILD = 2

packages/grafeas/grafeas/grafeas_v1/types/cvss.py

@@ -29,7 +29,16 @@
 
 
 class CVSSVersion(proto.Enum):
-    r"""CVSS Version."""
+    r"""CVSS Version.
+
+    Values:
+        CVSS_VERSION_UNSPECIFIED (0):
+
+        CVSS_VERSION_2 (1):
+
+        CVSS_VERSION_3 (2):
+
+    """
     CVSS_VERSION_UNSPECIFIED = 0
     CVSS_VERSION_2 = 1
     CVSS_VERSION_3 = 2
@@ -70,40 +79,102 @@ class CVSSv3(proto.Message):
     """
 
     class AttackVector(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            ATTACK_VECTOR_UNSPECIFIED (0):
+
+            ATTACK_VECTOR_NETWORK (1):
+
+            ATTACK_VECTOR_ADJACENT (2):
+
+            ATTACK_VECTOR_LOCAL (3):
+
+            ATTACK_VECTOR_PHYSICAL (4):
+
+        """
         ATTACK_VECTOR_UNSPECIFIED = 0
         ATTACK_VECTOR_NETWORK = 1
         ATTACK_VECTOR_ADJACENT = 2
         ATTACK_VECTOR_LOCAL = 3
         ATTACK_VECTOR_PHYSICAL = 4
 
     class AttackComplexity(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            ATTACK_COMPLEXITY_UNSPECIFIED (0):
+
+            ATTACK_COMPLEXITY_LOW (1):
+
+            ATTACK_COMPLEXITY_HIGH (2):
+
+        """
         ATTACK_COMPLEXITY_UNSPECIFIED = 0
         ATTACK_COMPLEXITY_LOW = 1
         ATTACK_COMPLEXITY_HIGH = 2
 
     class PrivilegesRequired(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            PRIVILEGES_REQUIRED_UNSPECIFIED (0):
+
+            PRIVILEGES_REQUIRED_NONE (1):
+
+            PRIVILEGES_REQUIRED_LOW (2):
+
+            PRIVILEGES_REQUIRED_HIGH (3):
+
+        """
         PRIVILEGES_REQUIRED_UNSPECIFIED = 0
         PRIVILEGES_REQUIRED_NONE = 1
         PRIVILEGES_REQUIRED_LOW = 2
         PRIVILEGES_REQUIRED_HIGH = 3
 
     class UserInteraction(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            USER_INTERACTION_UNSPECIFIED (0):
+
+            USER_INTERACTION_NONE (1):
+
+            USER_INTERACTION_REQUIRED (2):
+
+        """
         USER_INTERACTION_UNSPECIFIED = 0
         USER_INTERACTION_NONE = 1
         USER_INTERACTION_REQUIRED = 2
 
     class Scope(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            SCOPE_UNSPECIFIED (0):
+
+            SCOPE_UNCHANGED (1):
+
+            SCOPE_CHANGED (2):
+
+        """
         SCOPE_UNSPECIFIED = 0
         SCOPE_UNCHANGED = 1
         SCOPE_CHANGED = 2
 
     class Impact(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            IMPACT_UNSPECIFIED (0):
+
+            IMPACT_HIGH (1):
+
+            IMPACT_LOW (2):
+
+            IMPACT_NONE (3):
+
+        """
         IMPACT_UNSPECIFIED = 0
         IMPACT_HIGH = 1
         IMPACT_LOW = 2
@@ -203,47 +274,120 @@ class CVSS(proto.Message):
     """
 
     class AttackVector(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            ATTACK_VECTOR_UNSPECIFIED (0):
+
+            ATTACK_VECTOR_NETWORK (1):
+
+            ATTACK_VECTOR_ADJACENT (2):
+
+            ATTACK_VECTOR_LOCAL (3):
+
+            ATTACK_VECTOR_PHYSICAL (4):
+
+        """
         ATTACK_VECTOR_UNSPECIFIED = 0
         ATTACK_VECTOR_NETWORK = 1
         ATTACK_VECTOR_ADJACENT = 2
         ATTACK_VECTOR_LOCAL = 3
         ATTACK_VECTOR_PHYSICAL = 4
 
     class AttackComplexity(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            ATTACK_COMPLEXITY_UNSPECIFIED (0):
+
+            ATTACK_COMPLEXITY_LOW (1):
+
+            ATTACK_COMPLEXITY_HIGH (2):
+
+        """
         ATTACK_COMPLEXITY_UNSPECIFIED = 0
         ATTACK_COMPLEXITY_LOW = 1
         ATTACK_COMPLEXITY_HIGH = 2
 
     class Authentication(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            AUTHENTICATION_UNSPECIFIED (0):
+
+            AUTHENTICATION_MULTIPLE (1):
+
+            AUTHENTICATION_SINGLE (2):
+
+            AUTHENTICATION_NONE (3):
+
+        """
         AUTHENTICATION_UNSPECIFIED = 0
         AUTHENTICATION_MULTIPLE = 1
         AUTHENTICATION_SINGLE = 2
         AUTHENTICATION_NONE = 3
 
     class PrivilegesRequired(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            PRIVILEGES_REQUIRED_UNSPECIFIED (0):
+
+            PRIVILEGES_REQUIRED_NONE (1):
+
+            PRIVILEGES_REQUIRED_LOW (2):
+
+            PRIVILEGES_REQUIRED_HIGH (3):
+
+        """
         PRIVILEGES_REQUIRED_UNSPECIFIED = 0
         PRIVILEGES_REQUIRED_NONE = 1
         PRIVILEGES_REQUIRED_LOW = 2
         PRIVILEGES_REQUIRED_HIGH = 3
 
     class UserInteraction(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            USER_INTERACTION_UNSPECIFIED (0):
+
+            USER_INTERACTION_NONE (1):
+
+            USER_INTERACTION_REQUIRED (2):
+
+        """
         USER_INTERACTION_UNSPECIFIED = 0
         USER_INTERACTION_NONE = 1
         USER_INTERACTION_REQUIRED = 2
 
     class Scope(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            SCOPE_UNSPECIFIED (0):
+
+            SCOPE_UNCHANGED (1):
+
+            SCOPE_CHANGED (2):
+
+        """
         SCOPE_UNSPECIFIED = 0
         SCOPE_UNCHANGED = 1
         SCOPE_CHANGED = 2
 
     class Impact(proto.Enum):
-        r""""""
+        r"""
+
+        Values:
+            IMPACT_UNSPECIFIED (0):
+
+            IMPACT_HIGH (1):
+
+            IMPACT_LOW (2):
+
+            IMPACT_NONE (3):
+
+        """
         IMPACT_UNSPECIFIED = 0
         IMPACT_HIGH = 1
         IMPACT_LOW = 2

packages/grafeas/grafeas/grafeas_v1/types/deployment.py

@@ -71,7 +71,18 @@ class DeploymentOccurrence(proto.Message):
     """
 
     class Platform(proto.Enum):
-        r"""Types of platforms."""
+        r"""Types of platforms.
+
+        Values:
+            PLATFORM_UNSPECIFIED (0):
+                Unknown.
+            GKE (1):
+                Google Container Engine.
+            FLEX (2):
+                Google App Engine: Flexible Environment.
+            CUSTOM (3):
+                Custom user-defined platform.
+        """
         PLATFORM_UNSPECIFIED = 0
         GKE = 1
         FLEX = 2

packages/grafeas/grafeas/grafeas_v1/types/discovery.py

@@ -80,14 +80,42 @@ class DiscoveryOccurrence(proto.Message):
     """
 
     class ContinuousAnalysis(proto.Enum):
-        r"""Whether the resource is continuously analyzed."""
+        r"""Whether the resource is continuously analyzed.
+
+        Values:
+            CONTINUOUS_ANALYSIS_UNSPECIFIED (0):
+                Unknown.
+            ACTIVE (1):
+                The resource is continuously analyzed.
+            INACTIVE (2):
+                The resource is ignored for continuous
+                analysis.
+        """
         CONTINUOUS_ANALYSIS_UNSPECIFIED = 0
         ACTIVE = 1
         INACTIVE = 2
 
     class AnalysisStatus(proto.Enum):
         r"""Analysis status for a resource. Currently for initial
         analysis only (not updated in continuous analysis).
+
+        Values:
+            ANALYSIS_STATUS_UNSPECIFIED (0):
+                Unknown.
+            PENDING (1):
+                Resource is known but no action has been
+                taken yet.
+            SCANNING (2):
+                Resource is being analyzed.
+            FINISHED_SUCCESS (3):
+                Analysis has finished successfully.
+            COMPLETE (3):
+                Analysis has completed.
+            FINISHED_FAILED (4):
+                Analysis has finished unsuccessfully, the
+                analysis itself is in a bad state.
+            FINISHED_UNSUPPORTED (5):
+                The resource is known not to be supported.
         """
         _pb_options = {"allow_alias": True}
         ANALYSIS_STATUS_UNSPECIFIED = 0