feat: add StyleInfo to document.proto

feat: add IMPORTING enum to State in processor.proto
chore: updated comments

PiperOrigin-RevId: 540937637

google/cloud/documentai/v1/barcode.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

google/cloud/documentai/v1/document.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -64,7 +64,8 @@ message Document {
       // Font size for the text.
       float size = 1;
 
-      // Unit for the font size. Follows CSS naming (in, px, pt, etc.).
+      // Unit for the font size. Follows CSS naming (such as `in`, `px`, and
+      // `pt`).
       string unit = 2;
     }
 
@@ -78,17 +79,18 @@ message Document {
     // Text background color.
     google.type.Color background_color = 3;
 
-    // Font weight. Possible values are normal, bold, bolder, and lighter.
-    // https://www.w3schools.com/cssref/pr_font_weight.asp
+    // [Font weight](https://www.w3schools.com/cssref/pr_font_weight.asp).
+    // Possible values are `normal`, `bold`, `bolder`, and `lighter`.
     string font_weight = 4;
 
-    // Text style. Possible values are normal, italic, and oblique.
-    // https://www.w3schools.com/cssref/pr_font_font-style.asp
+    // [Text style](https://www.w3schools.com/cssref/pr_font_font-style.asp).
+    // Possible values are `normal`, `italic`, and `oblique`.
     string text_style = 5;
 
-    // Text decoration. Follows CSS standard.
-    // <text-decoration-line> <text-decoration-color> <text-decoration-style>
-    // https://www.w3schools.com/cssref/pr_text_text-decoration.asp
+    // [Text
+    // decoration](https://www.w3schools.com/cssref/pr_text_text-decoration.asp).
+    // Follows CSS standard. <text-decoration-line> <text-decoration-color>
+    // <text-decoration-style>
     string text_decoration = 6;
 
     // Font size.
@@ -118,7 +120,9 @@ message Document {
       // Raw byte content of the image.
       bytes content = 1;
 
-      // Encoding mime type for the image.
+      // Encoding [media type (MIME
+      // type)](https://www.iana.org/assignments/media-types/media-types.xhtml)
+      // for the image.
       string mime_type = 2;
 
       // Width of the image in pixels.
@@ -255,6 +259,59 @@ message Document {
         Type type = 1;
       }
 
+      // Font and other text style attributes.
+      message StyleInfo {
+        // Font size in points (`1` point is `¹⁄₇₂` inches).
+        int32 font_size = 1;
+
+        // Font size in pixels, equal to _unrounded
+        // [font_size][google.cloud.documentai.v1.Document.Page.Token.StyleInfo.font_size]_
+        // * _resolution_ ÷ `72.0`.
+        double pixel_font_size = 2;
+
+        // Letter spacing in points.
+        double letter_spacing = 3;
+
+        // Name or style of the font.
+        string font_type = 4;
+
+        // Whether the text is bold (equivalent to
+        // [font_weight][google.cloud.documentai.v1.Document.Page.Token.StyleInfo.font_weight]
+        // is at least `700`).
+        bool bold = 5;
+
+        // Whether the text is italic.
+        bool italic = 6;
+
+        // Whether the text is underlined.
+        bool underlined = 7;
+
+        // Whether the text is strikethrough.
+        bool strikeout = 8;
+
+        // Whether the text is a subscript.
+        bool subscript = 9;
+
+        // Whether the text is a superscript.
+        bool superscript = 10;
+
+        // Whether the text is in small caps.
+        bool smallcaps = 11;
+
+        // TrueType weight on a scale `100` (thin) to `1000` (ultra-heavy).
+        // Normal is `400`, bold is `700`.
+        int32 font_weight = 12;
+
+        // Whether the text is handwritten.
+        bool handwritten = 13;
+
+        // Color of the text.
+        google.type.Color text_color = 14;
+
+        // Color of the background.
+        google.type.Color background_color = 15;
+      }
+
       // [Layout][google.cloud.documentai.v1.Document.Page.Layout] for
       // [Token][google.cloud.documentai.v1.Document.Page.Token].
       Layout layout = 1;
@@ -268,6 +325,9 @@ message Document {
 
       // The history of this annotation.
       Provenance provenance = 4 [deprecated = true];
+
+      // Text style attributes.
+      StyleInfo style_info = 5;
     }
 
     // A detected symbol.
@@ -333,7 +393,7 @@ message Document {
       repeated DetectedLanguage detected_languages = 4;
 
       // The history of this table.
-      Provenance provenance = 5;
+      Provenance provenance = 5 [deprecated = true];
     }
 
     // A form field detected on the page.
@@ -388,16 +448,16 @@ message Document {
 
     // Detected language for a structural component.
     message DetectedLanguage {
-      // The BCP-47 language code, such as `en-US` or `sr-Latn`. For more
-      // information, see
-      // https://www.unicode.org/reports/tr35/#Unicode_locale_identifier.
+      // The [BCP-47 language
+      // code](https://www.unicode.org/reports/tr35/#Unicode_locale_identifier),
+      // such as `en-US` or `sr-Latn`.
       string language_code = 1;
 
       // Confidence of detected language. Range `[0, 1]`.
       float confidence = 2;
     }
 
-    // Image Quality Scores for the page image
+    // Image quality scores for the page image.
     message ImageQualityScores {
       // Image Quality Defects
       message DetectedDefect {
@@ -413,12 +473,12 @@ message Document {
         // - `quality/defect_glare`
         string type = 1;
 
-        // Confidence of detected defect. Range `[0, 1]` where 1 indicates
-        // strong confidence of that the defect exists.
+        // Confidence of detected defect. Range `[0, 1]` where `1` indicates
+        // strong confidence that the defect exists.
         float confidence = 2;
       }
 
-      // The overall quality score. Range `[0, 1]` where 1 is perfect quality.
+      // The overall quality score. Range `[0, 1]` where `1` is perfect quality.
       float quality_score = 1;
 
       // A list of detected defects.
@@ -482,7 +542,7 @@ message Document {
     // A list of detected barcodes.
     repeated DetectedBarcode detected_barcodes = 15;
 
-    // Image Quality Scores.
+    // Image quality scores.
     ImageQualityScores image_quality_scores = 17;
 
     // The history of this page.
@@ -736,9 +796,9 @@ message Document {
       REMOVE = 2;
 
       // Updates any fields within the given provenance scope of the message. It
-      // 'overwrites'  the fields rather than replacing them.  This is
-      // especially relevant when we just want to update a field value of an
-      // entity without also affecting all the child properties.
+      // overwrites the fields rather than replacing them.  Use this when you
+      // want to update a field value of an entity without also updating all the
+      // child properties.
       UPDATE = 7;
 
       // Currently unused. Replace an element identified by `parent`.
@@ -835,10 +895,9 @@ message Document {
   // Original source document from the user.
   oneof source {
     // Optional. Currently supports Google Cloud Storage URI of the form
-    //    `gs://bucket_name/object_name`. Object versioning is not supported.
-    //    See [Google Cloud Storage Request
-    //    URIs](https://cloud.google.com/storage/docs/reference-uris) for more
-    //    info.
+    // `gs://bucket_name/object_name`. Object versioning is not supported.
+    // For more information, refer to [Google Cloud Storage Request
+    // URIs](https://cloud.google.com/storage/docs/reference-uris).
     string uri = 1 [(google.api.field_behavior) = OPTIONAL];
 
     // Optional. Inline document content, represented as a stream of bytes.
@@ -847,9 +906,8 @@ message Document {
     bytes content = 2 [(google.api.field_behavior) = OPTIONAL];
   }
 
-  // An IANA published MIME type (also referred to as media type). For more
-  // information, see
-  // https://www.iana.org/assignments/media-types/media-types.xhtml.
+  // An IANA published [media type (MIME
+  // type)](https://www.iana.org/assignments/media-types/media-types.xhtml).
   string mime_type = 3;
 
   // Optional. UTF-8 encoded text in reading order from the document.

google/cloud/documentai/v1/document_io.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

google/cloud/documentai/v1/document_processor_service.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -49,7 +49,7 @@ option (google.api.resource_definition) = {
   pattern: "projects/{project}/locations/{location}"
 };
 
-// Service to call Cloud DocumentAI to process documents according to the
+// Service to call Document AI to process documents according to the
 // processor's definition. Processors are built using state-of-the-art Google
 // AI such as natural language, computer vision, and translation to extract
 // structured information from unstructured or semi-structured documents.
@@ -90,8 +90,9 @@ service DocumentProcessorService {
     };
   }
 
-  // Fetches processor types. Note that we do not use ListProcessorTypes here
-  // because it is not paginated.
+  // Fetches processor types. Note that we don't use
+  // [ListProcessorTypes][google.cloud.documentai.v1.DocumentProcessorService.ListProcessorTypes]
+  // here, because it isn't paginated.
   rpc FetchProcessorTypes(FetchProcessorTypesRequest)
       returns (FetchProcessorTypesResponse) {
     option (google.api.http) = {
@@ -135,7 +136,7 @@ service DocumentProcessorService {
 
   // Trains a new processor version.
   // Operation metadata is returned as
-  // cloud_documentai_core.TrainProcessorVersionMetadata.
+  // [TrainProcessorVersionMetadata][google.cloud.documentai.v1.TrainProcessorVersionMetadata].
   rpc TrainProcessorVersion(TrainProcessorVersionRequest)
       returns (google.longrunning.Operation) {
     option (google.api.http) = {
@@ -209,8 +210,9 @@ service DocumentProcessorService {
     };
   }
 
-  // Creates a processor from the type processor that the user chose.
-  // The processor will be at "ENABLED" state by default after its creation.
+  // Creates a processor from the
+  // [ProcessorType][google.cloud.documentai.v1.ProcessorType] provided. The
+  // processor will be at `ENABLED` state by default after its creation.
   rpc CreateProcessor(CreateProcessorRequest) returns (Processor) {
     option (google.api.http) = {
       post: "/v1/{parent=projects/*/locations/*}/processors"
@@ -324,7 +326,9 @@ service DocumentProcessorService {
   }
 }
 
-// Request message for the process document method.
+// Request message for the
+// [ProcessDocument][google.cloud.documentai.v1.DocumentProcessorService.ProcessDocument]
+// method.
 message ProcessRequest {
   // The document payload.
   oneof source {
@@ -350,13 +354,14 @@ message ProcessRequest {
     (google.api.resource_reference) = { type: "*" }
   ];
 
-  // Whether Human Review feature should be skipped for this request. Default to
-  // false.
+  // Whether human review should be skipped for this request. Default to
+  // `false`.
   bool skip_human_review = 3;
 
-  // Specifies which fields to include in ProcessResponse's document.
-  // Only supports top level document and pages field so it must be in the form
-  // of `{document_field_name}` or `pages.{page_field_name}`.
+  // Specifies which fields to include in the
+  // [ProcessResponse.document][google.cloud.documentai.v1.ProcessResponse.document]
+  // output. Only supports top-level document and pages field, so it must be in
+  // the form of `{document_field_name}` or `pages.{page_field_name}`.
   google.protobuf.FieldMask field_mask = 6;
 }
 
@@ -368,7 +373,7 @@ message HumanReviewStatus {
     STATE_UNSPECIFIED = 0;
 
     // Human review is skipped for the document. This can happen because human
-    // review is not enabled on the processor or the processing request has
+    // review isn't enabled on the processor or the processing request has
     // been set to skip this document.
     SKIPPED = 1;
 
@@ -379,7 +384,8 @@ message HumanReviewStatus {
     IN_PROGRESS = 3;
 
     // Some error happened during triggering human review, see the
-    // [state_message] for details.
+    // [state_message][google.cloud.documentai.v1.HumanReviewStatus.state_message]
+    // for details.
     ERROR = 4;
   }
 
@@ -390,13 +396,17 @@ message HumanReviewStatus {
   string state_message = 2;
 
   // The name of the operation triggered by the processed document. This field
-  // is populated only when the [state] is [HUMAN_REVIEW_IN_PROGRESS]. It has
-  // the same response type and metadata as the long running operation returned
-  // by [ReviewDocument] method.
+  // is populated only when the
+  // [state][google.cloud.documentai.v1.HumanReviewStatus.state] is
+  // `HUMAN_REVIEW_IN_PROGRESS`. It has the same response type and metadata as
+  // the long-running operation returned by
+  // [ReviewDocument][google.cloud.documentai.v1.DocumentProcessorService.ReviewDocument].
   string human_review_operation = 3;
 }
 
-// Response message for the process document method.
+// Response message for the
+// [ProcessDocument][google.cloud.documentai.v1.DocumentProcessorService.ProcessDocument]
+// method.
 message ProcessResponse {
   // The document payload, will populate fields based on the processor's
   // behavior.
@@ -406,7 +416,8 @@ message ProcessResponse {
   HumanReviewStatus human_review_status = 3;
 }
 
-// Request message for batch process document method.
+// Request message for
+// [BatchProcessDocuments][google.cloud.documentai.v1.DocumentProcessorService.BatchProcessDocuments].
 message BatchProcessRequest {
   // Required. The resource name of
   // [Processor][google.cloud.documentai.v1.Processor] or
@@ -419,34 +430,40 @@ message BatchProcessRequest {
     (google.api.resource_reference) = { type: "*" }
   ];
 
-  // The input documents for batch process.
+  // The input documents for the
+  // [BatchProcessDocuments][google.cloud.documentai.v1.DocumentProcessorService.BatchProcessDocuments]
+  // method.
   BatchDocumentsInputConfig input_documents = 5;
 
-  // The overall output config for batch process.
+  // The output configuration for the
+  // [BatchProcessDocuments][google.cloud.documentai.v1.DocumentProcessorService.BatchProcessDocuments]
+  // method.
   DocumentOutputConfig document_output_config = 6;
 
-  // Whether Human Review feature should be skipped for this request. Default to
-  // false.
+  // Whether human review should be skipped for this request. Default to
+  // `false`.
   bool skip_human_review = 4;
 }
 
-// Response message for batch process document method.
+// Response message for
+// [BatchProcessDocuments][google.cloud.documentai.v1.DocumentProcessorService.BatchProcessDocuments].
 message BatchProcessResponse {}
 
-// The long running operation metadata for batch process method.
+// The long-running operation metadata for
+// [BatchProcessDocuments][google.cloud.documentai.v1.DocumentProcessorService.BatchProcessDocuments].
 message BatchProcessMetadata {
   // The status of a each individual document in the batch process.
   message IndividualProcessStatus {
-    // The source of the document, same as the [input_gcs_source] field in the
-    // request when the batch process started. The batch process is started by
-    // take snapshot of that document, since a user can move or change that
-    // document during the process.
+    // The source of the document, same as the
+    // [input_gcs_source][google.cloud.documentai.v1.BatchProcessMetadata.IndividualProcessStatus.input_gcs_source]
+    // field in the request when the batch process started.
     string input_gcs_source = 1;
 
     // The status processing the document.
     google.rpc.Status status = 2;
 
-    // The output_gcs_destination (in the request as `output_gcs_destination`)
+    // The Cloud Storage output destination (in the request as
+    // [DocumentOutputConfig.GcsOutputConfig.gcs_uri][google.cloud.documentai.v1.DocumentOutputConfig.GcsOutputConfig.gcs_uri])
     // of the processed document if it was successful, otherwise empty.
     string output_gcs_destination = 3;
 
@@ -495,11 +512,13 @@ message BatchProcessMetadata {
   repeated IndividualProcessStatus individual_process_statuses = 5;
 }
 
-// Request message for fetch processor types.
+// Request message for the
+// [FetchProcessorTypes][google.cloud.documentai.v1.DocumentProcessorService.FetchProcessorTypes]
+// method. Some processor types may require the project be added to an
+// allowlist.
 message FetchProcessorTypesRequest {
-  // Required. The project of processor type to list.
-  // The available processor types may depend on the allow-listing on projects.
-  // Format: `projects/{project}/locations/{location}`
+  // Required. The location of processor types to list.
+  // Format: `projects/{project}/locations/{location}`.
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -508,17 +527,21 @@ message FetchProcessorTypesRequest {
   ];
 }
 
-// Response message for fetch processor types.
+// Response message for the
+// [FetchProcessorTypes][google.cloud.documentai.v1.DocumentProcessorService.FetchProcessorTypes]
+// method.
 message FetchProcessorTypesResponse {
   // The list of processor types.
   repeated ProcessorType processor_types = 1;
 }
 
-// Request message for list processor types.
+// Request message for the
+// [ListProcessorTypes][google.cloud.documentai.v1.DocumentProcessorService.ListProcessorTypes]
+// method. Some processor types may require the project be added to an
+// allowlist.
 message ListProcessorTypesRequest {
-  // Required. The location of processor type to list.
-  // The available processor types may depend on the allow-listing on projects.
-  // Format: `projects/{project}/locations/{location}`
+  // Required. The location of processor types to list.
+  // Format: `projects/{project}/locations/{location}`.
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -527,15 +550,17 @@ message ListProcessorTypesRequest {
   ];
 
   // The maximum number of processor types to return.
-  // If unspecified, at most 100 processor types will be returned.
-  // The maximum value is 500; values above 500 will be coerced to 500.
+  // If unspecified, at most `100` processor types will be returned.
+  // The maximum value is `500`. Values above `500` will be coerced to `500`.
   int32 page_size = 2;
 
   // Used to retrieve the next page of results, empty if at the end of the list.
   string page_token = 3;
 }
 
-// Response message for list processor types.
+// Response message for the
+// [ListProcessorTypes][google.cloud.documentai.v1.DocumentProcessorService.ListProcessorTypes]
+// method.
 message ListProcessorTypesResponse {
   // The processor types.
   repeated ProcessorType processor_types = 1;
@@ -556,8 +581,8 @@ message ListProcessorsRequest {
   ];
 
   // The maximum number of processors to return.
-  // If unspecified, at most 50 processors will be returned.
-  // The maximum value is 100; values above 100 will be coerced to 100.
+  // If unspecified, at most `50` processors will be returned.
+  // The maximum value is `100`. Values above `100` will be coerced to `100`.
   int32 page_size = 2;
 
   // We will return the processors sorted by creation time. The page token
@@ -565,7 +590,9 @@ message ListProcessorsRequest {
   string page_token = 3;
 }
 
-// Response message for list processors.
+// Response message for the
+// [ListProcessors][google.cloud.documentai.v1.DocumentProcessorService.ListProcessors]
+// method.
 message ListProcessorsResponse {
   // The list of processors.
   repeated Processor processors = 1;
@@ -574,7 +601,9 @@ message ListProcessorsResponse {
   string next_page_token = 2;
 }
 
-// Request message for get processor.
+// Request message for the
+// [GetProcessorType][google.cloud.documentai.v1.DocumentProcessorService.GetProcessorType]
+// method.
 message GetProcessorTypeRequest {
   // Required. The processor type resource name.
   string name = 1 [
@@ -585,7 +614,9 @@ message GetProcessorTypeRequest {
   ];
 }
 
-// Request message for get processor.
+// Request message for the
+// [GetProcessor][google.cloud.documentai.v1.DocumentProcessorService.GetProcessor]
+// method.
 message GetProcessorRequest {
   // Required. The processor resource name.
   string name = 1 [
@@ -596,7 +627,9 @@ message GetProcessorRequest {
   ];
 }
 
-// Request message for get processor version.
+// Request message for the
+// [GetProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.GetProcessorVersion]
+// method.
 message GetProcessorVersionRequest {
   // Required. The processor resource name.
   string name = 1 [
@@ -620,8 +653,8 @@ message ListProcessorVersionsRequest {
   ];
 
   // The maximum number of processor versions to return.
-  // If unspecified, at most 10 processor versions will be returned.
-  // The maximum value is 20; values above 20 will be coerced to 20.
+  // If unspecified, at most `10` processor versions will be returned.
+  // The maximum value is `20`. Values above `20` will be coerced to `20`.
   int32 page_size = 2;
 
   // We will return the processor versions sorted by creation time. The page
@@ -629,7 +662,9 @@ message ListProcessorVersionsRequest {
   string page_token = 3;
 }
 
-// Response message for list processors.
+// Response message for the
+// [ListProcessorVersions][google.cloud.documentai.v1.DocumentProcessorService.ListProcessorVersions]
+// method.
 message ListProcessorVersionsResponse {
   // The list of processors.
   repeated ProcessorVersion processor_versions = 1;
@@ -638,7 +673,9 @@ message ListProcessorVersionsResponse {
   string next_page_token = 2;
 }
 
-// Request message for the delete processor version method.
+// Request message for the
+// [DeleteProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.DeleteProcessorVersion]
+// method.
 message DeleteProcessorVersionRequest {
   // Required. The processor version resource name to be deleted.
   string name = 1 [
@@ -649,13 +686,17 @@ message DeleteProcessorVersionRequest {
   ];
 }
 
-// The long running operation metadata for delete processor version method.
+// The long-running operation metadata for the
+// [DeleteProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.DeleteProcessorVersion]
+// method.
 message DeleteProcessorVersionMetadata {
-  // The basic metadata of the long running operation.
+  // The basic metadata of the long-running operation.
   CommonOperationMetadata common_metadata = 1;
 }
 
-// Request message for the deploy processor version method.
+// Request message for the
+// [DeployProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.DeployProcessorVersion]
+// method.
 message DeployProcessorVersionRequest {
   // Required. The processor version resource name to be deployed.
   string name = 1 [
@@ -666,16 +707,22 @@ message DeployProcessorVersionRequest {
   ];
 }
 
-// Response message for the deploy processor version method.
+// Response message for the
+// [DeployProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.DeployProcessorVersion]
+// method.
 message DeployProcessorVersionResponse {}
 
-// The long running operation metadata for deploy processor version method.
+// The long-running operation metadata for the
+// [DeployProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.DeployProcessorVersion]
+// method.
 message DeployProcessorVersionMetadata {
-  // The basic metadata of the long running operation.
+  // The basic metadata of the long-running operation.
   CommonOperationMetadata common_metadata = 1;
 }
 
-// Request message for the undeploy processor version method.
+// Request message for the
+// [UndeployProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.UndeployProcessorVersion]
+// method.
 message UndeployProcessorVersionRequest {
   // Required. The processor version resource name to be undeployed.
   string name = 1 [
@@ -686,19 +733,24 @@ message UndeployProcessorVersionRequest {
   ];
 }
 
-// Response message for the undeploy processor version method.
+// Response message for the
+// [UndeployProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.UndeployProcessorVersion]
+// method.
 message UndeployProcessorVersionResponse {}
 
-// The long running operation metadata for the undeploy processor version
+// The long-running operation metadata for the
+// [UndeployProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.UndeployProcessorVersion]
 // method.
 message UndeployProcessorVersionMetadata {
-  // The basic metadata of the long running operation.
+  // The basic metadata of the long-running operation.
   CommonOperationMetadata common_metadata = 1;
 }
 
-// Request message for create a processor. Notice this request is sent to
-// a regionalized backend service, and if the processor type is not available
-// on that region, the creation will fail.
+// Request message for the
+// [CreateProcessor][google.cloud.documentai.v1.DocumentProcessorService.CreateProcessor]
+// method. Notice this request is sent to a regionalized backend service. If the
+// [ProcessorType][google.cloud.documentai.v1.ProcessorType] isn't available in
+// that region, the creation fails.
 message CreateProcessorRequest {
   // Required. The parent (project and location) under which to create the
   // processor. Format: `projects/{project}/locations/{location}`
@@ -709,13 +761,17 @@ message CreateProcessorRequest {
     }
   ];
 
-  // Required. The processor to be created, requires [processor_type] and
-  // [display_name] to be set. Also, the processor is under CMEK if CMEK fields
-  // are set.
+  // Required. The processor to be created, requires
+  // [Processor.type][google.cloud.documentai.v1.Processor.type] and
+  // [Processor.display_name]][] to be set. Also, the
+  // [Processor.kms_key_name][google.cloud.documentai.v1.Processor.kms_key_name]
+  // field must be set if the processor is under CMEK.
   Processor processor = 2 [(google.api.field_behavior) = REQUIRED];
 }
 
-// Request message for the delete processor method.
+// Request message for the
+// [DeleteProcessor][google.cloud.documentai.v1.DocumentProcessorService.DeleteProcessor]
+// method.
 message DeleteProcessorRequest {
   // Required. The processor resource name to be deleted.
   string name = 1 [
@@ -726,13 +782,17 @@ message DeleteProcessorRequest {
   ];
 }
 
-// The long running operation metadata for delete processor method.
+// The long-running operation metadata for the
+// [DeleteProcessor][google.cloud.documentai.v1.DocumentProcessorService.DeleteProcessor]
+// method.
 message DeleteProcessorMetadata {
-  // The basic metadata of the long running operation.
+  // The basic metadata of the long-running operation.
   CommonOperationMetadata common_metadata = 5;
 }
 
-// Request message for the enable processor method.
+// Request message for the
+// [EnableProcessor][google.cloud.documentai.v1.DocumentProcessorService.EnableProcessor]
+// method.
 message EnableProcessorRequest {
   // Required. The processor resource name to be enabled.
   string name = 1 [
@@ -743,17 +803,22 @@ message EnableProcessorRequest {
   ];
 }
 
-// Response message for the enable processor method.
-// Intentionally empty proto for adding fields in future.
+// Response message for the
+// [EnableProcessor][google.cloud.documentai.v1.DocumentProcessorService.EnableProcessor]
+// method. Intentionally empty proto for adding fields in future.
 message EnableProcessorResponse {}
 
-// The long running operation metadata for enable processor method.
+// The long-running operation metadata for the
+// [EnableProcessor][google.cloud.documentai.v1.DocumentProcessorService.EnableProcessor]
+// method.
 message EnableProcessorMetadata {
-  // The basic metadata of the long running operation.
+  // The basic metadata of the long-running operation.
   CommonOperationMetadata common_metadata = 5;
 }
 
-// Request message for the disable processor method.
+// Request message for the
+// [DisableProcessor][google.cloud.documentai.v1.DocumentProcessorService.DisableProcessor]
+// method.
 message DisableProcessorRequest {
   // Required. The processor resource name to be disabled.
   string name = 1 [
@@ -764,17 +829,22 @@ message DisableProcessorRequest {
   ];
 }
 
-// Response message for the disable processor method.
-// Intentionally empty proto for adding fields in future.
+// Response message for the
+// [DisableProcessor][google.cloud.documentai.v1.DocumentProcessorService.DisableProcessor]
+// method. Intentionally empty proto for adding fields in future.
 message DisableProcessorResponse {}
 
-// The long running operation metadata for disable processor method.
+// The long-running operation metadata for the
+// [DisableProcessor][google.cloud.documentai.v1.DocumentProcessorService.DisableProcessor]
+// method.
 message DisableProcessorMetadata {
-  // The basic metadata of the long running operation.
+  // The basic metadata of the long-running operation.
   CommonOperationMetadata common_metadata = 5;
 }
 
-// Request message for the set default processor version method.
+// Request message for the
+// [SetDefaultProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.SetDefaultProcessorVersion]
+// method.
 message SetDefaultProcessorVersionRequest {
   // Required. The resource name of the
   // [Processor][google.cloud.documentai.v1.Processor] to change default
@@ -798,19 +868,25 @@ message SetDefaultProcessorVersionRequest {
   ];
 }
 
-// Response message for set default processor version method.
+// Response message for the
+// [SetDefaultProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.SetDefaultProcessorVersion]
+// method.
 message SetDefaultProcessorVersionResponse {}
 
-// The long running operation metadata for set default processor version
+// The long-running operation metadata for the
+// [SetDefaultProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.SetDefaultProcessorVersion]
 // method.
 message SetDefaultProcessorVersionMetadata {
-  // The basic metadata of the long running operation.
+  // The basic metadata of the long-running operation.
   CommonOperationMetadata common_metadata = 1;
 }
 
-// Request message for the create processor version method.
+// Request message for the
+// [TrainProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.TrainProcessorVersion]
+// method.
 message TrainProcessorVersionRequest {
-  // The input data used to train a new `ProcessorVersion`.
+  // The input data used to train a new
+  // [ProcessorVersion][google.cloud.documentai.v1.ProcessorVersion].
   message InputData {
     // The documents used for training the new version.
     BatchDocumentsInputConfig training_documents = 3;
@@ -836,7 +912,8 @@ message TrainProcessorVersionRequest {
   // Optional. The schema the processor version will be trained with.
   DocumentSchema document_schema = 10 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. The input data used to train the `ProcessorVersion`.
+  // Optional. The input data used to train the
+  // [ProcessorVersion][google.cloud.documentai.v1.ProcessorVersion].
   InputData input_data = 4 [(google.api.field_behavior) = OPTIONAL];
 
   // Optional. The processor version to use as a base for training. This
@@ -845,7 +922,8 @@ message TrainProcessorVersionRequest {
   string base_processor_version = 8 [(google.api.field_behavior) = OPTIONAL];
 }
 
-// The response for the TrainProcessorVersion method.
+// The response for
+// [TrainProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.TrainProcessorVersion].
 message TrainProcessorVersionResponse {
   // The resource name of the processor version produced by training.
   string processor_version = 1;
@@ -873,7 +951,7 @@ message TrainProcessorVersionMetadata {
     repeated google.rpc.Status dataset_errors = 2;
   }
 
-  // The basic metadata of the long running operation.
+  // The basic metadata of the long-running operation.
   CommonOperationMetadata common_metadata = 1;
 
   // The training dataset validation information.
@@ -883,7 +961,9 @@ message TrainProcessorVersionMetadata {
   DatasetValidation test_dataset_validation = 3;
 }
 
-// Request message for review document method.
+// Request message for the
+// [ReviewDocument][google.cloud.documentai.v1.DocumentProcessorService.ReviewDocument]
+// method.
 message ReviewDocumentRequest {
   // The priority level of the human review task.
   enum Priority {
@@ -901,8 +981,9 @@ message ReviewDocumentRequest {
     Document inline_document = 4;
   }
 
-  // Required. The resource name of the HumanReviewConfig that the document will
-  // be reviewed with.
+  // Required. The resource name of the
+  // [HumanReviewConfig][google.cloud.documentai.v1.HumanReviewConfig] that the
+  // document will be reviewed with.
   string human_review_config = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -920,7 +1001,9 @@ message ReviewDocumentRequest {
   DocumentSchema document_schema = 6;
 }
 
-// Response message for review document method.
+// Response message for the
+// [ReviewDocument][google.cloud.documentai.v1.DocumentProcessorService.ReviewDocument]
+// method.
 message ReviewDocumentResponse {
   // Possible states of the review operation.
   enum State {
@@ -945,16 +1028,20 @@ message ReviewDocumentResponse {
   string rejection_reason = 3;
 }
 
-// The long running operation metadata for review document method.
+// The long-running operation metadata for the
+// [ReviewDocument][google.cloud.documentai.v1.DocumentProcessorService.ReviewDocument]
+// method.
 message ReviewDocumentOperationMetadata {
-  // The basic metadata of the long running operation.
+  // The basic metadata of the long-running operation.
   CommonOperationMetadata common_metadata = 5;
 
   // The Crowd Compute question ID.
   string question_id = 6;
 }
 
-// Evaluates the given ProcessorVersion against the supplied documents.
+// Evaluates the given
+// [ProcessorVersion][google.cloud.documentai.v1.ProcessorVersion] against the
+// supplied documents.
 message EvaluateProcessorVersionRequest {
   // Required. The resource name of the
   // [ProcessorVersion][google.cloud.documentai.v1.ProcessorVersion] to
@@ -973,13 +1060,17 @@ message EvaluateProcessorVersionRequest {
       [(google.api.field_behavior) = OPTIONAL];
 }
 
-// Metadata of the EvaluateProcessorVersion method.
+// Metadata of the
+// [EvaluateProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.EvaluateProcessorVersion]
+// method.
 message EvaluateProcessorVersionMetadata {
-  // The basic metadata of the long running operation.
+  // The basic metadata of the long-running operation.
   CommonOperationMetadata common_metadata = 1;
 }
 
-// Metadata of the EvaluateProcessorVersion method.
+// Response of the
+// [EvaluateProcessorVersion][google.cloud.documentai.v1.DocumentProcessorService.EvaluateProcessorVersion]
+// method.
 message EvaluateProcessorVersionResponse {
   // The resource name of the created evaluation.
   string evaluation = 2;
@@ -998,7 +1089,8 @@ message GetEvaluationRequest {
   ];
 }
 
-// Retrieves a list of evaluations for a given ProcessorVersion.
+// Retrieves a list of evaluations for a given
+// [ProcessorVersion][google.cloud.documentai.v1.ProcessorVersion].
 message ListEvaluationsRequest {
   // Required. The resource name of the
   // [ProcessorVersion][google.cloud.documentai.v1.ProcessorVersion] to list
@@ -1012,8 +1104,8 @@ message ListEvaluationsRequest {
   ];
 
   // The standard list page size.
-  // If unspecified, at most 5 evaluations will be returned.
-  // The maximum value is 100; values above 100 will be coerced to 100.
+  // If unspecified, at most `5` evaluations are returned.
+  // The maximum value is `100`. Values above `100` are coerced to `100`.
   int32 page_size = 2;
 
   // A page token, received from a previous `ListEvaluations` call.
@@ -1021,7 +1113,7 @@ message ListEvaluationsRequest {
   string page_token = 3;
 }
 
-// The response from ListEvaluations.
+// The response from `ListEvaluations`.
 message ListEvaluationsResponse {
   // The evaluations requested.
   repeated Evaluation evaluations = 1;

google/cloud/documentai/v1/document_schema.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -92,16 +92,15 @@ message DocumentSchema {
     string display_name = 13;
 
     // Name of the type. It must be unique within the schema file and
-    // cannot be a 'Common Type'.  Besides that we use the following naming
-    // conventions:
+    // cannot be a "Common Type".  The following naming conventions are used:
     //
-    // - *use `snake_casing`*
-    // - name matching is case-sensitive
+    // - Use `snake_casing`.
+    // - Name matching is case-sensitive.
     // - Maximum 64 characters.
     // - Must start with a letter.
     // - Allowed characters: ASCII letters `[a-z0-9_-]`.  (For backward
     //   compatibility internal infrastructure and tooling can handle any ascii
-    //   character)
+    //   character.)
     // - The `/` is sometimes used to denote a property of a type.  For example
     //   `line_item/amount`.  This convention is deprecated, but will still be
     //   honored for backward compatibility.
@@ -117,8 +116,8 @@ message DocumentSchema {
 
   // Metadata for global schema behavior.
   message Metadata {
-    // If true, a `document` entity type can be applied to subdocument (
-    // splitting). Otherwise, it can only be applied to the entire document
+    // If true, a `document` entity type can be applied to subdocument
+    // (splitting). Otherwise, it can only be applied to the entire document
     // (classification).
     bool document_splitter = 1;
 

google/cloud/documentai/v1/documentai_v1_grpc_service_config.json

@@ -5,7 +5,21 @@
         {
           "service": "google.cloud.documentai.v1.DocumentProcessorService",
           "method": "ProcessDocument"
-        },
+        }
+      ],
+      "timeout": "300s",
+      "retryPolicy": {
+        "initialBackoff": "0.100s",
+        "maxBackoff": "60s",
+        "backoffMultiplier": 1.3,
+        "retryableStatusCodes": [
+          "DEADLINE_EXCEEDED",
+          "UNAVAILABLE"
+        ]
+      }
+    },
+    {
+      "name": [
         {
           "service": "google.cloud.documentai.v1.DocumentProcessorService",
           "method": "BatchProcessDocuments"

google/cloud/documentai/v1/evaluation.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

google/cloud/documentai/v1/geometry.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

google/cloud/documentai/v1/operation_metadata.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

google/cloud/documentai/v1/processor.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -31,10 +31,9 @@ option php_namespace = "Google\\Cloud\\DocumentAI\\V1";
 option ruby_package = "Google::Cloud::DocumentAI::V1";
 
 // A processor version is an implementation of a processor. Each processor
-// can have multiple versions, pre-trained by Google internally or up-trained
-// by the customer. At a time, a processor can only have one default version
-// version. So the processor's behavior (when processing documents) is defined
-// by a default version
+// can have multiple versions, pretrained by Google internally or uptrained
+// by the customer. A processor can only have one default version at a time.
+// Its document-processing behavior is defined by that version.
 message ProcessorVersion {
   option (google.api.resource) = {
     type: "documentai.googleapis.com/ProcessorVersion"
@@ -78,6 +77,9 @@ message ProcessorVersion {
 
     // The processor version failed and is in an indeterminate state.
     FAILED = 7;
+
+    // The processor version is being imported.
+    IMPORTING = 8;
   }
 
   // The resource name of the processor version.
@@ -106,7 +108,7 @@ message ProcessorVersion {
   // The KMS key version with which data is encrypted.
   string kms_key_version_name = 10;
 
-  // Denotes that this ProcessorVersion is managed by google.
+  // Denotes that this `ProcessorVersion` is managed by Google.
   bool google_managed = 11;
 
   // If set, information about the eventual deprecation of this version.
@@ -163,8 +165,8 @@ message Processor {
     (google.api.field_behavior) = OUTPUT_ONLY
   ];
 
-  // The processor type, e.g., `OCR_PROCESSOR`, `INVOICE_PROCESSOR`, etc.
-  // To get a list of processors types, see
+  // The processor type, such as: `OCR_PROCESSOR`, `INVOICE_PROCESSOR`.
+  // To get a list of processor types, see
   // [FetchProcessorTypes][google.cloud.documentai.v1.DocumentProcessorService.FetchProcessorTypes].
   string type = 2;
 
@@ -189,7 +191,7 @@ message Processor {
   // The time the processor was created.
   google.protobuf.Timestamp create_time = 7;
 
-  // The KMS key used for encryption/decryption in CMEK scenarios.
-  // See https://cloud.google.com/security-key-management.
+  // The [KMS key](https://cloud.google.com/security-key-management) used for
+  // encryption and decryption in CMEK scenarios.
   string kms_key_name = 8;
 }

google/cloud/documentai/v1/processor_type.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -37,7 +37,8 @@ message ProcessorType {
 
   // The location information about where the processor is available.
   message LocationInfo {
-    // The location id, currently must be one of [us, eu].
+    // The location ID. For supported locations, refer to [regional and
+    // multi-regional support](/document-ai/docs/regions).
     string location_id = 1;
   }
 
@@ -45,7 +46,7 @@ message ProcessorType {
   // Format: `projects/{project}/processorTypes/{processor_type}`
   string name = 1;
 
-  // The processor type, e.g., `OCR_PROCESSOR`, `INVOICE_PROCESSOR`, etc.
+  // The processor type, such as: `OCR_PROCESSOR`, `INVOICE_PROCESSOR`.
   string type = 2;
 
   // The processor category, used by UI to group processor types.