docs: Add documentation for enums (#464)

* 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-automl/google/cloud/automl_v1/services/auto_ml/client.py

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

packages/google-cloud-automl/google/cloud/automl_v1/services/prediction_service/client.py

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

packages/google-cloud-automl/google/cloud/automl_v1/types/classification.py

@@ -29,7 +29,16 @@
 
 
 class ClassificationType(proto.Enum):
-    r"""Type of the classification problem."""
+    r"""Type of the classification problem.
+
+    Values:
+        CLASSIFICATION_TYPE_UNSPECIFIED (0):
+            An un-set value of this enum.
+        MULTICLASS (1):
+            At most one label is allowed per example.
+        MULTILABEL (2):
+            Multiple labels are allowed for one example.
+    """
     CLASSIFICATION_TYPE_UNSPECIFIED = 0
     MULTICLASS = 1
     MULTILABEL = 2

packages/google-cloud-automl/google/cloud/automl_v1/types/data_items.py

@@ -111,7 +111,20 @@ class DocumentDimensions(proto.Message):
     """
 
     class DocumentDimensionUnit(proto.Enum):
-        r"""Unit of the document dimension."""
+        r"""Unit of the document dimension.
+
+        Values:
+            DOCUMENT_DIMENSION_UNIT_UNSPECIFIED (0):
+                Should not be used.
+            INCH (1):
+                Document dimension is measured in inches.
+            CENTIMETER (2):
+                Document dimension is measured in
+                centimeters.
+            POINT (3):
+                Document dimension is measured in points. 72
+                points = 1 inch.
+        """
         DOCUMENT_DIMENSION_UNIT_UNSPECIFIED = 0
         INCH = 1
         CENTIMETER = 2
@@ -182,6 +195,42 @@ class Layout(proto.Message):
         class TextSegmentType(proto.Enum):
             r"""The type of TextSegment in the context of the original
             document.
+
+            Values:
+                TEXT_SEGMENT_TYPE_UNSPECIFIED (0):
+                    Should not be used.
+                TOKEN (1):
+                    The text segment is a token. e.g. word.
+                PARAGRAPH (2):
+                    The text segment is a paragraph.
+                FORM_FIELD (3):
+                    The text segment is a form field.
+                FORM_FIELD_NAME (4):
+                    The text segment is the name part of a form field. It will
+                    be treated as child of another FORM_FIELD TextSegment if its
+                    span is subspan of another TextSegment with type FORM_FIELD.
+                FORM_FIELD_CONTENTS (5):
+                    The text segment is the text content part of a form field.
+                    It will be treated as child of another FORM_FIELD
+                    TextSegment if its span is subspan of another TextSegment
+                    with type FORM_FIELD.
+                TABLE (6):
+                    The text segment is a whole table, including
+                    headers, and all rows.
+                TABLE_HEADER (7):
+                    The text segment is a table's headers. It
+                    will be treated as child of another TABLE
+                    TextSegment if its span is subspan of another
+                    TextSegment with type TABLE.
+                TABLE_ROW (8):
+                    The text segment is a row in table. It will
+                    be treated as child of another TABLE TextSegment
+                    if its span is subspan of another TextSegment
+                    with type TABLE.
+                TABLE_CELL (9):
+                    The text segment is a cell in table. It will be treated as
+                    child of another TABLE_ROW TextSegment if its span is
+                    subspan of another TextSegment with type TABLE_ROW.
             """
             TEXT_SEGMENT_TYPE_UNSPECIFIED = 0
             TOKEN = 1

packages/google-cloud-automl/google/cloud/automl_v1/types/model.py

@@ -107,7 +107,17 @@ class Model(proto.Message):
     """
 
     class DeploymentState(proto.Enum):
-        r"""Deployment state of the model."""
+        r"""Deployment state of the model.
+
+        Values:
+            DEPLOYMENT_STATE_UNSPECIFIED (0):
+                Should not be used, an un-set enum has this
+                value by default.
+            DEPLOYED (1):
+                Model is deployed.
+            UNDEPLOYED (2):
+                Model is not deployed.
+        """
         DEPLOYMENT_STATE_UNSPECIFIED = 0
         DEPLOYED = 1
         UNDEPLOYED = 2

packages/google-cloud-automl/google/cloud/automl_v1beta1/services/auto_ml/client.py

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

packages/google-cloud-automl/google/cloud/automl_v1beta1/services/prediction_service/client.py

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

packages/google-cloud-automl/google/cloud/automl_v1beta1/types/classification.py

@@ -32,7 +32,16 @@
 
 
 class ClassificationType(proto.Enum):
-    r"""Type of the classification problem."""
+    r"""Type of the classification problem.
+
+    Values:
+        CLASSIFICATION_TYPE_UNSPECIFIED (0):
+            An un-set value of this enum.
+        MULTICLASS (1):
+            At most one label is allowed per example.
+        MULTILABEL (2):
+            Multiple labels are allowed for one example.
+    """
     CLASSIFICATION_TYPE_UNSPECIFIED = 0
     MULTICLASS = 1
     MULTILABEL = 2

packages/google-cloud-automl/google/cloud/automl_v1beta1/types/data_items.py

@@ -128,7 +128,20 @@ class DocumentDimensions(proto.Message):
     """
 
     class DocumentDimensionUnit(proto.Enum):
-        r"""Unit of the document dimension."""
+        r"""Unit of the document dimension.
+
+        Values:
+            DOCUMENT_DIMENSION_UNIT_UNSPECIFIED (0):
+                Should not be used.
+            INCH (1):
+                Document dimension is measured in inches.
+            CENTIMETER (2):
+                Document dimension is measured in
+                centimeters.
+            POINT (3):
+                Document dimension is measured in points. 72
+                points = 1 inch.
+        """
         DOCUMENT_DIMENSION_UNIT_UNSPECIFIED = 0
         INCH = 1
         CENTIMETER = 2
@@ -200,6 +213,42 @@ class Layout(proto.Message):
         class TextSegmentType(proto.Enum):
             r"""The type of TextSegment in the context of the original
             document.
+
+            Values:
+                TEXT_SEGMENT_TYPE_UNSPECIFIED (0):
+                    Should not be used.
+                TOKEN (1):
+                    The text segment is a token. e.g. word.
+                PARAGRAPH (2):
+                    The text segment is a paragraph.
+                FORM_FIELD (3):
+                    The text segment is a form field.
+                FORM_FIELD_NAME (4):
+                    The text segment is the name part of a form field. It will
+                    be treated as child of another FORM_FIELD TextSegment if its
+                    span is subspan of another TextSegment with type FORM_FIELD.
+                FORM_FIELD_CONTENTS (5):
+                    The text segment is the text content part of a form field.
+                    It will be treated as child of another FORM_FIELD
+                    TextSegment if its span is subspan of another TextSegment
+                    with type FORM_FIELD.
+                TABLE (6):
+                    The text segment is a whole table, including
+                    headers, and all rows.
+                TABLE_HEADER (7):
+                    The text segment is a table's headers. It
+                    will be treated as child of another TABLE
+                    TextSegment if its span is subspan of another
+                    TextSegment with type TABLE.
+                TABLE_ROW (8):
+                    The text segment is a row in table. It will
+                    be treated as child of another TABLE TextSegment
+                    if its span is subspan of another TextSegment
+                    with type TABLE.
+                TABLE_CELL (9):
+                    The text segment is a cell in table. It will be treated as
+                    child of another TABLE_ROW TextSegment if its span is
+                    subspan of another TextSegment with type TABLE_ROW.
             """
             TEXT_SEGMENT_TYPE_UNSPECIFIED = 0
             TOKEN = 1

packages/google-cloud-automl/google/cloud/automl_v1beta1/types/data_types.py

@@ -31,6 +31,38 @@
 class TypeCode(proto.Enum):
     r"""``TypeCode`` is used as a part of
     [DataType][google.cloud.automl.v1beta1.DataType].
+
+    Values:
+        TYPE_CODE_UNSPECIFIED (0):
+            Not specified. Should not be used.
+        FLOAT64 (3):
+            Encoded as ``number``, or the strings ``"NaN"``,
+            ``"Infinity"``, or ``"-Infinity"``.
+        TIMESTAMP (4):
+            Must be between 0AD and 9999AD. Encoded as ``string``
+            according to
+            [time_format][google.cloud.automl.v1beta1.DataType.time_format],
+            or, if that format is not set, then in RFC 3339
+            ``date-time`` format, where ``time-offset`` = ``"Z"`` (e.g.
+            1985-04-12T23:20:50.52Z).
+        STRING (6):
+            Encoded as ``string``.
+        ARRAY (8):
+            Encoded as ``list``, where the list elements are represented
+            according to
+
+            [list_element_type][google.cloud.automl.v1beta1.DataType.list_element_type].
+        STRUCT (9):
+            Encoded as ``struct``, where field values are represented
+            according to
+            [struct_type][google.cloud.automl.v1beta1.DataType.struct_type].
+        CATEGORY (10):
+            Values of this type are not further understood by AutoML,
+            e.g. AutoML is unable to tell the order of values (as it
+            could with FLOAT64), or is unable to say if one value
+            contains another (as it could with STRING). Encoded as
+            ``string`` (bytes should be base64-encoded, as described in
+            RFC 4648, section 4).
     """
     TYPE_CODE_UNSPECIFIED = 0
     FLOAT64 = 3

packages/google-cloud-automl/google/cloud/automl_v1beta1/types/model.py

@@ -106,7 +106,17 @@ class Model(proto.Message):
     """
 
     class DeploymentState(proto.Enum):
-        r"""Deployment state of the model."""
+        r"""Deployment state of the model.
+
+        Values:
+            DEPLOYMENT_STATE_UNSPECIFIED (0):
+                Should not be used, an un-set enum has this
+                value by default.
+            DEPLOYED (1):
+                Model is deployed.
+            UNDEPLOYED (2):
+                Model is not deployed.
+        """
         DEPLOYMENT_STATE_UNSPECIFIED = 0
         DEPLOYED = 1
         UNDEPLOYED = 2

packages/google-cloud-automl/samples/generated_samples/snippet_metadata_google.cloud.automl.v1.json

@@ -8,7 +8,7 @@
     ],
     "language": "PYTHON",
     "name": "google-cloud-automl",
-    "version": "2.10.0"
+    "version": "0.1.0"
   },
   "snippets": [
     {

packages/google-cloud-automl/samples/generated_samples/snippet_metadata_google.cloud.automl.v1beta1.json

@@ -8,7 +8,7 @@
     ],
     "language": "PYTHON",
     "name": "google-cloud-automl",
-    "version": "2.10.0"
+    "version": "0.1.0"
   },
   "snippets": [
     {