docs: Add documentation for enums (#513)

* 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/google-cloud-vision/google/cloud/vision_v1/services/image_annotator/client.py

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

packages/google-cloud-vision/google/cloud/vision_v1/services/product_search/client.py

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

packages/google-cloud-vision/google/cloud/vision_v1/types/image_annotator.py

@@ -77,6 +77,20 @@
 class Likelihood(proto.Enum):
     r"""A bucketized representation of likelihood, which is intended
     to give clients highly stable results across model upgrades.
+
+    Values:
+        UNKNOWN (0):
+            Unknown likelihood.
+        VERY_UNLIKELY (1):
+            It is very unlikely.
+        UNLIKELY (2):
+            It is unlikely.
+        POSSIBLE (3):
+            It is possible.
+        LIKELY (4):
+            It is likely.
+        VERY_LIKELY (5):
+            It is very likely.
     """
     UNKNOWN = 0
     VERY_UNLIKELY = 1
@@ -107,7 +121,43 @@ class Feature(proto.Message):
     """
 
     class Type(proto.Enum):
-        r"""Type of Google Cloud Vision API feature to be extracted."""
+        r"""Type of Google Cloud Vision API feature to be extracted.
+
+        Values:
+            TYPE_UNSPECIFIED (0):
+                Unspecified feature type.
+            FACE_DETECTION (1):
+                Run face detection.
+            LANDMARK_DETECTION (2):
+                Run landmark detection.
+            LOGO_DETECTION (3):
+                Run logo detection.
+            LABEL_DETECTION (4):
+                Run label detection.
+            TEXT_DETECTION (5):
+                Run text detection / optical character recognition (OCR).
+                Text detection is optimized for areas of text within a
+                larger image; if the image is a document, use
+                ``DOCUMENT_TEXT_DETECTION`` instead.
+            DOCUMENT_TEXT_DETECTION (11):
+                Run dense text document OCR. Takes precedence when both
+                ``DOCUMENT_TEXT_DETECTION`` and ``TEXT_DETECTION`` are
+                present.
+            SAFE_SEARCH_DETECTION (6):
+                Run Safe Search to detect potentially unsafe
+                or undesirable content.
+            IMAGE_PROPERTIES (7):
+                Compute a set of image properties, such as
+                the image's dominant colors.
+            CROP_HINTS (9):
+                Run crop hints.
+            WEB_DETECTION (10):
+                Run web detection.
+            PRODUCT_SEARCH (12):
+                Run Product Search.
+            OBJECT_LOCALIZATION (19):
+                Run localizer for object detection.
+        """
         TYPE_UNSPECIFIED = 0
         FACE_DETECTION = 1
         LANDMARK_DETECTION = 2
@@ -283,6 +333,83 @@ class Type(proto.Enum):
             vantage of the viewer of the image without considering mirror
             projections typical of photos. So, ``LEFT_EYE``, typically, is the
             person's right eye.
+
+            Values:
+                UNKNOWN_LANDMARK (0):
+                    Unknown face landmark detected. Should not be
+                    filled.
+                LEFT_EYE (1):
+                    Left eye.
+                RIGHT_EYE (2):
+                    Right eye.
+                LEFT_OF_LEFT_EYEBROW (3):
+                    Left of left eyebrow.
+                RIGHT_OF_LEFT_EYEBROW (4):
+                    Right of left eyebrow.
+                LEFT_OF_RIGHT_EYEBROW (5):
+                    Left of right eyebrow.
+                RIGHT_OF_RIGHT_EYEBROW (6):
+                    Right of right eyebrow.
+                MIDPOINT_BETWEEN_EYES (7):
+                    Midpoint between eyes.
+                NOSE_TIP (8):
+                    Nose tip.
+                UPPER_LIP (9):
+                    Upper lip.
+                LOWER_LIP (10):
+                    Lower lip.
+                MOUTH_LEFT (11):
+                    Mouth left.
+                MOUTH_RIGHT (12):
+                    Mouth right.
+                MOUTH_CENTER (13):
+                    Mouth center.
+                NOSE_BOTTOM_RIGHT (14):
+                    Nose, bottom right.
+                NOSE_BOTTOM_LEFT (15):
+                    Nose, bottom left.
+                NOSE_BOTTOM_CENTER (16):
+                    Nose, bottom center.
+                LEFT_EYE_TOP_BOUNDARY (17):
+                    Left eye, top boundary.
+                LEFT_EYE_RIGHT_CORNER (18):
+                    Left eye, right corner.
+                LEFT_EYE_BOTTOM_BOUNDARY (19):
+                    Left eye, bottom boundary.
+                LEFT_EYE_LEFT_CORNER (20):
+                    Left eye, left corner.
+                RIGHT_EYE_TOP_BOUNDARY (21):
+                    Right eye, top boundary.
+                RIGHT_EYE_RIGHT_CORNER (22):
+                    Right eye, right corner.
+                RIGHT_EYE_BOTTOM_BOUNDARY (23):
+                    Right eye, bottom boundary.
+                RIGHT_EYE_LEFT_CORNER (24):
+                    Right eye, left corner.
+                LEFT_EYEBROW_UPPER_MIDPOINT (25):
+                    Left eyebrow, upper midpoint.
+                RIGHT_EYEBROW_UPPER_MIDPOINT (26):
+                    Right eyebrow, upper midpoint.
+                LEFT_EAR_TRAGION (27):
+                    Left ear tragion.
+                RIGHT_EAR_TRAGION (28):
+                    Right ear tragion.
+                LEFT_EYE_PUPIL (29):
+                    Left eye pupil.
+                RIGHT_EYE_PUPIL (30):
+                    Right eye pupil.
+                FOREHEAD_GLABELLA (31):
+                    Forehead glabella.
+                CHIN_GNATHION (32):
+                    Chin gnathion.
+                CHIN_LEFT_GONION (33):
+                    Chin left gonion.
+                CHIN_RIGHT_GONION (34):
+                    Chin right gonion.
+                LEFT_CHEEK_CENTER (35):
+                    Left cheek center.
+                RIGHT_CHEEK_CENTER (36):
+                    Right cheek center.
             """
             UNKNOWN_LANDMARK = 0
             LEFT_EYE = 1
@@ -1559,7 +1686,20 @@ class OperationMetadata(proto.Message):
     """
 
     class State(proto.Enum):
-        r"""Batch operation states."""
+        r"""Batch operation states.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Invalid.
+            CREATED (1):
+                Request is received.
+            RUNNING (2):
+                Request is actively being processed.
+            DONE (3):
+                The batch processing is done.
+            CANCELLED (4):
+                The batch processing was cancelled.
+        """
         STATE_UNSPECIFIED = 0
         CREATED = 1
         RUNNING = 2

packages/google-cloud-vision/google/cloud/vision_v1/types/product_search_service.py

@@ -997,6 +997,24 @@ class BatchOperationMetadata(proto.Message):
     class State(proto.Enum):
         r"""Enumerates the possible states that the batch request can be
         in.
+
+        Values:
+            STATE_UNSPECIFIED (0):
+                Invalid.
+            PROCESSING (1):
+                Request is actively being processed.
+            SUCCESSFUL (2):
+                The request is done and at least one item has
+                been successfully processed.
+            FAILED (3):
+                The request is done and no item has been
+                successfully processed.
+            CANCELLED (4):
+                The request is done after the
+                longrunning.Operations.CancelOperation has been
+                called by the user.  Any records that were
+                processed before the cancel command are output
+                as specified in the request.
         """
         STATE_UNSPECIFIED = 0
         PROCESSING = 1

packages/google-cloud-vision/google/cloud/vision_v1/types/text_annotation.py

@@ -82,7 +82,24 @@ class DetectedBreak(proto.Message):
         """
 
         class BreakType(proto.Enum):
-            r"""Enum to denote the type of break found. New line, space etc."""
+            r"""Enum to denote the type of break found. New line, space etc.
+
+            Values:
+                UNKNOWN (0):
+                    Unknown break label type.
+                SPACE (1):
+                    Regular space.
+                SURE_SPACE (2):
+                    Sure space (very wide).
+                EOL_SURE_SPACE (3):
+                    Line-wrapping break.
+                HYPHEN (4):
+                    End-line hyphen that is not present in text; does not
+                    co-occur with ``SPACE``, ``LEADER_SPACE``, or
+                    ``LINE_BREAK``.
+                LINE_BREAK (5):
+                    Line break that ends a paragraph.
+            """
             UNKNOWN = 0
             SPACE = 1
             SURE_SPACE = 2
@@ -221,7 +238,22 @@ class Block(proto.Message):
     """
 
     class BlockType(proto.Enum):
-        r"""Type of a block (text, image etc) as identified by OCR."""
+        r"""Type of a block (text, image etc) as identified by OCR.
+
+        Values:
+            UNKNOWN (0):
+                Unknown block type.
+            TEXT (1):
+                Regular text block.
+            TABLE (2):
+                Table block.
+            PICTURE (3):
+                Image block.
+            RULER (4):
+                Horizontal/vertical line box.
+            BARCODE (5):
+                Barcode block.
+        """
         UNKNOWN = 0
         TEXT = 1
         TABLE = 2

packages/google-cloud-vision/google/cloud/vision_v1p1beta1/services/image_annotator/client.py

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