fix: improve docstrings, and add more field validation (#224)

fix: improve docstrings, and add more field validation

Author: yoshi-automation

packages/google-cloud-language/protos/google/cloud/language/v1/language_service.proto

@@ -18,45 +18,53 @@ syntax = "proto3";
 package google.cloud.language.v1;
 
 import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
 
 option go_package = "google.golang.org/genproto/googleapis/cloud/language/v1;language";
 option java_multiple_files = true;
 option java_outer_classname = "LanguageServiceProto";
 option java_package = "com.google.cloud.language.v1";
 
+
 // Provides text analysis operations such as sentiment analysis and entity
 // recognition.
 service LanguageService {
+  option (google.api.default_host) = "language.googleapis.com";
+  option (google.api.oauth_scopes) =
+    "https://www.googleapis.com/auth/cloud-language,"
+    "https://www.googleapis.com/auth/cloud-platform";
   // Analyzes the sentiment of the provided text.
-  rpc AnalyzeSentiment(AnalyzeSentimentRequest)
-      returns (AnalyzeSentimentResponse) {
+  rpc AnalyzeSentiment(AnalyzeSentimentRequest) returns (AnalyzeSentimentResponse) {
     option (google.api.http) = {
       post: "/v1/documents:analyzeSentiment"
       body: "*"
     };
+    option (google.api.method_signature) = "document,encoding_type";
+    option (google.api.method_signature) = "document";
   }
 
   // Finds named entities (currently proper names and common nouns) in the text
   // along with entity types, salience, mentions for each entity, and
   // other properties.
-  rpc AnalyzeEntities(AnalyzeEntitiesRequest)
-      returns (AnalyzeEntitiesResponse) {
+  rpc AnalyzeEntities(AnalyzeEntitiesRequest) returns (AnalyzeEntitiesResponse) {
     option (google.api.http) = {
       post: "/v1/documents:analyzeEntities"
       body: "*"
     };
+    option (google.api.method_signature) = "document,encoding_type";
+    option (google.api.method_signature) = "document";
   }
 
-  // Finds entities, similar to
-  // [AnalyzeEntities][google.cloud.language.v1.LanguageService.AnalyzeEntities]
-  // in the text and analyzes sentiment associated with each entity and its
-  // mentions.
-  rpc AnalyzeEntitySentiment(AnalyzeEntitySentimentRequest)
-      returns (AnalyzeEntitySentimentResponse) {
+  // Finds entities, similar to [AnalyzeEntities][google.cloud.language.v1.LanguageService.AnalyzeEntities] in the text and analyzes
+  // sentiment associated with each entity and its mentions.
+  rpc AnalyzeEntitySentiment(AnalyzeEntitySentimentRequest) returns (AnalyzeEntitySentimentResponse) {
     option (google.api.http) = {
       post: "/v1/documents:analyzeEntitySentiment"
       body: "*"
     };
+    option (google.api.method_signature) = "document,encoding_type";
+    option (google.api.method_signature) = "document";
   }
 
   // Analyzes the syntax of the text and provides sentence boundaries and
@@ -67,6 +75,8 @@ service LanguageService {
       post: "/v1/documents:analyzeSyntax"
       body: "*"
     };
+    option (google.api.method_signature) = "document,encoding_type";
+    option (google.api.method_signature) = "document";
   }
 
   // Classifies a document into categories.
@@ -75,6 +85,7 @@ service LanguageService {
       post: "/v1/documents:classifyText"
       body: "*"
     };
+    option (google.api.method_signature) = "document";
   }
 
   // A convenience method that provides all the features that analyzeSentiment,
@@ -84,6 +95,8 @@ service LanguageService {
       post: "/v1/documents:annotateText"
       body: "*"
     };
+    option (google.api.method_signature) = "document,features,encoding_type";
+    option (google.api.method_signature) = "document,features";
   }
 }
 
@@ -111,6 +124,7 @@ message Document {
   // Google Cloud Storage URI.
   oneof source {
     // The content of the input in string format.
+    // Cloud audit logging exempt since it is based on user data.
     string content = 2;
 
     // The Google Cloud Storage URI where the file content is located.
@@ -137,16 +151,19 @@ message Sentence {
   TextSpan text = 1;
 
   // For calls to [AnalyzeSentiment][] or if
-  // [AnnotateTextRequest.Features.extract_document_sentiment][google.cloud.language.v1.AnnotateTextRequest.Features.extract_document_sentiment]
-  // is set to true, this field will contain the sentiment for the sentence.
+  // [AnnotateTextRequest.Features.extract_document_sentiment][google.cloud.language.v1.AnnotateTextRequest.Features.extract_document_sentiment] is set to
+  // true, this field will contain the sentiment for the sentence.
   Sentiment sentiment = 2;
 }
 
 // Represents a phrase in the text that is a known entity, such as
 // a person, an organization, or location. The API associates information, such
 // as salience and mentions, with entities.
 message Entity {
-  // The type of the entity.
+  // The type of the entity. For most entity types, the associated metadata is a
+  // Wikipedia URL (`wikipedia_url`) and Knowledge Graph MID (`mid`). The table
+  // below lists the associated fields for entities that have different
+  // metadata.
   enum Type {
     // Unknown
     UNKNOWN = 0;
@@ -163,28 +180,53 @@ message Entity {
     // Event
     EVENT = 4;
 
-    // Work of art
+    // Artwork
     WORK_OF_ART = 5;
 
-    // Consumer goods
+    // Consumer product
     CONSUMER_GOOD = 6;
 
-    // Other types
+    // Other types of entities
     OTHER = 7;
 
-    // Phone number
+    // Phone number<br><br>
+    // The metadata lists the phone number, formatted according to local
+    // convention, plus whichever additional elements appear in the text:<ul>
+    // <li><code>number</code> &ndash; the actual number, broken down into
+    // sections as per local convention</li> <li><code>national_prefix</code>
+    // &ndash; country code, if detected</li> <li><code>area_code</code> &ndash;
+    // region or area code, if detected</li> <li><code>extension</code> &ndash;
+    // phone extension (to be dialed after connection), if detected</li></ul>
     PHONE_NUMBER = 9;
 
-    // Address
+    // Address<br><br>
+    // The metadata identifies the street number and locality plus whichever
+    // additional elements appear in the text:<ul>
+    // <li><code>street_number</code> &ndash; street number</li>
+    // <li><code>locality</code> &ndash; city or town</li>
+    // <li><code>street_name</code> &ndash; street/route name, if detected</li>
+    // <li><code>postal_code</code> &ndash; postal code, if detected</li>
+    // <li><code>country</code> &ndash; country, if detected</li>
+    // <li><code>broad_region</code> &ndash; administrative area, such as the
+    // state, if detected</li> <li><code>narrow_region</code> &ndash; smaller
+    // administrative area, such as county, if detected</li>
+    // <li><code>sublocality</code> &ndash; used in Asian addresses to demark a
+    // district within a city, if detected</li></ul>
     ADDRESS = 10;
 
-    // Date
+    // Date<br><br>
+    // The metadata identifies the components of the date:<ul>
+    // <li><code>year</code> &ndash; four digit year, if detected</li>
+    // <li><code>month</code> &ndash; two digit month number, if detected</li>
+    // <li><code>day</code> &ndash; two digit day number, if detected</li></ul>
     DATE = 11;
 
-    // Number
+    // Number<br><br>
+    // The metadata is the number itself.
     NUMBER = 12;
 
-    // Price
+    // Price<br><br>
+    // The metadata identifies the <code>value</code> and <code>currency</code>.
     PRICE = 13;
   }
 
@@ -196,8 +238,9 @@ message Entity {
 
   // Metadata associated with the entity.
   //
-  // Currently, Wikipedia URLs and Knowledge Graph MIDs are provided, if
-  // available. The associated keys are "wikipedia_url" and "mid", respectively.
+  // For most entity types, the metadata is a Wikipedia URL (`wikipedia_url`)
+  // and Knowledge Graph MID (`mid`), if they are available. For the metadata
+  // associated with other entity types, see the Type table below.
   map<string, string> metadata = 3;
 
   // The salience score associated with the entity in the [0, 1.0] range.
@@ -213,9 +256,9 @@ message Entity {
   repeated EntityMention mentions = 5;
 
   // For calls to [AnalyzeEntitySentiment][] or if
-  // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1.AnnotateTextRequest.Features.extract_entity_sentiment]
-  // is set to true, this field will contain the aggregate sentiment expressed
-  // for this entity in the provided document.
+  // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1.AnnotateTextRequest.Features.extract_entity_sentiment] is set to
+  // true, this field will contain the aggregate sentiment expressed for this
+  // entity in the provided document.
   Sentiment sentiment = 6;
 }
 
@@ -892,9 +935,9 @@ message EntityMention {
   Type type = 2;
 
   // For calls to [AnalyzeEntitySentiment][] or if
-  // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1.AnnotateTextRequest.Features.extract_entity_sentiment]
-  // is set to true, this field will contain the sentiment expressed for this
-  // mention of the entity in the provided document.
+  // [AnnotateTextRequest.Features.extract_entity_sentiment][google.cloud.language.v1.AnnotateTextRequest.Features.extract_entity_sentiment] is set to
+  // true, this field will contain the sentiment expressed for this mention of
+  // the entity in the provided document.
   Sentiment sentiment = 3;
 }
 
@@ -904,9 +947,7 @@ message TextSpan {
   string content = 1;
 
   // The API calculates the beginning offset of the content in the original
-  // document according to the
-  // [EncodingType][google.cloud.language.v1.EncodingType] specified in the API
-  // request.
+  // document according to the [EncodingType][google.cloud.language.v1.EncodingType] specified in the API request.
   int32 begin_offset = 2;
 }
 
@@ -924,7 +965,7 @@ message ClassificationCategory {
 // The sentiment analysis request message.
 message AnalyzeSentimentRequest {
   // Input document.
-  Document document = 1;
+  Document document = 1 [(google.api.field_behavior) = REQUIRED];
 
   // The encoding type used by the API to calculate sentence offsets.
   EncodingType encoding_type = 2;
@@ -937,8 +978,7 @@ message AnalyzeSentimentResponse {
 
   // The language of the text, which will be the same as the language specified
   // in the request or, if not specified, the automatically-detected language.
-  // See [Document.language][google.cloud.language.v1.Document.language] field
-  // for more details.
+  // See [Document.language][google.cloud.language.v1.Document.language] field for more details.
   string language = 2;
 
   // The sentiment for all the sentences in the document.
@@ -948,7 +988,7 @@ message AnalyzeSentimentResponse {
 // The entity-level sentiment analysis request message.
 message AnalyzeEntitySentimentRequest {
   // Input document.
-  Document document = 1;
+  Document document = 1 [(google.api.field_behavior) = REQUIRED];
 
   // The encoding type used by the API to calculate offsets.
   EncodingType encoding_type = 2;
@@ -961,15 +1001,14 @@ message AnalyzeEntitySentimentResponse {
 
   // The language of the text, which will be the same as the language specified
   // in the request or, if not specified, the automatically-detected language.
-  // See [Document.language][google.cloud.language.v1.Document.language] field
-  // for more details.
+  // See [Document.language][google.cloud.language.v1.Document.language] field for more details.
   string language = 2;
 }
 
 // The entity analysis request message.
 message AnalyzeEntitiesRequest {
   // Input document.
-  Document document = 1;
+  Document document = 1 [(google.api.field_behavior) = REQUIRED];
 
   // The encoding type used by the API to calculate offsets.
   EncodingType encoding_type = 2;
@@ -982,15 +1021,14 @@ message AnalyzeEntitiesResponse {
 
   // The language of the text, which will be the same as the language specified
   // in the request or, if not specified, the automatically-detected language.
-  // See [Document.language][google.cloud.language.v1.Document.language] field
-  // for more details.
+  // See [Document.language][google.cloud.language.v1.Document.language] field for more details.
   string language = 2;
 }
 
 // The syntax analysis request message.
 message AnalyzeSyntaxRequest {
   // Input document.
-  Document document = 1;
+  Document document = 1 [(google.api.field_behavior) = REQUIRED];
 
   // The encoding type used by the API to calculate offsets.
   EncodingType encoding_type = 2;
@@ -1006,15 +1044,14 @@ message AnalyzeSyntaxResponse {
 
   // The language of the text, which will be the same as the language specified
   // in the request or, if not specified, the automatically-detected language.
-  // See [Document.language][google.cloud.language.v1.Document.language] field
-  // for more details.
+  // See [Document.language][google.cloud.language.v1.Document.language] field for more details.
   string language = 3;
 }
 
 // The document classification request message.
 message ClassifyTextRequest {
   // Input document.
-  Document document = 1;
+  Document document = 1 [(google.api.field_behavior) = REQUIRED];
 }
 
 // The document classification response message.
@@ -1046,10 +1083,10 @@ message AnnotateTextRequest {
   }
 
   // Input document.
-  Document document = 1;
+  Document document = 1 [(google.api.field_behavior) = REQUIRED];
 
   // The enabled features.
-  Features features = 2;
+  Features features = 2 [(google.api.field_behavior) = REQUIRED];
 
   // The encoding type used by the API to calculate offsets.
   EncodingType encoding_type = 3;
@@ -1077,8 +1114,7 @@ message AnnotateTextResponse {
 
   // The language of the text, which will be the same as the language specified
   // in the request or, if not specified, the automatically-detected language.
-  // See [Document.language][google.cloud.language.v1.Document.language] field
-  // for more details.
+  // See [Document.language][google.cloud.language.v1.Document.language] field for more details.
   string language = 5;
 
   // Categories identified in the input document.