From c0d0bd7a84f6eba145544e1bfaa4946b969f84b1 Mon Sep 17 00:00:00 2001 From: Yoshi Automation Bot <44816363+yoshi-automation@users.noreply.github.com> Date: Thu, 4 Apr 2019 08:26:25 -0700 Subject: [PATCH] fix: improve docstrings, and add more field validation (#224) fix: improve docstrings, and add more field validation --- .../cloud/language/v1/language_service.proto | 134 +++++++++++------- .../cloud/language/v1/doc_language_service.js | 87 +++++++----- .../src/v1/language_service_client.js | 6 +- packages/google-cloud-language/synth.metadata | 10 +- 4 files changed, 147 insertions(+), 90 deletions(-) diff --git a/packages/google-cloud-language/protos/google/cloud/language/v1/language_service.proto b/packages/google-cloud-language/protos/google/cloud/language/v1/language_service.proto index 7a15c8bf14c..41d92f344c7 100644 --- a/packages/google-cloud-language/protos/google/cloud/language/v1/language_service.proto +++ b/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,8 +151,8 @@ 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; } @@ -146,7 +160,10 @@ message Sentence { // 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

+ // The metadata lists the phone number, formatted according to local + // convention, plus whichever additional elements appear in the text: PHONE_NUMBER = 9; - // Address + // Address

+ // The metadata identifies the street number and locality plus whichever + // additional elements appear in the text: ADDRESS = 10; - // Date + // Date

+ // The metadata identifies the components of the date: DATE = 11; - // Number + // Number

+ // The metadata is the number itself. NUMBER = 12; - // Price + // Price

+ // The metadata identifies the value and currency. 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 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. diff --git a/packages/google-cloud-language/src/v1/doc/google/cloud/language/v1/doc_language_service.js b/packages/google-cloud-language/src/v1/doc/google/cloud/language/v1/doc_language_service.js index 0b77e711c24..bb6be889493 100644 --- a/packages/google-cloud-language/src/v1/doc/google/cloud/language/v1/doc_language_service.js +++ b/packages/google-cloud-language/src/v1/doc/google/cloud/language/v1/doc_language_service.js @@ -28,6 +28,7 @@ * * @property {string} content * The content of the input in string format. + * Cloud audit logging exempt since it is based on user data. * * @property {string} gcsContentUri * The Google Cloud Storage URI where the file content is located. @@ -87,8 +88,8 @@ const Document = { * * @property {Object} sentiment * For calls to AnalyzeSentiment or if - * AnnotateTextRequest.Features.extract_document_sentiment - * is set to true, this field will contain the sentiment for the sentence. + * AnnotateTextRequest.Features.extract_document_sentiment is set to + * true, this field will contain the sentiment for the sentence. * * This object should have the same structure as [Sentiment]{@link google.cloud.language.v1.Sentiment} * @@ -116,8 +117,9 @@ const Sentence = { * @property {Object.} metadata * 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. * * @property {number} salience * The salience score associated with the entity in the [0, 1.0] range. @@ -135,9 +137,9 @@ const Sentence = { * * @property {Object} sentiment * For calls to AnalyzeEntitySentiment or if - * 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 is set to + * true, this field will contain the aggregate sentiment expressed for this + * entity in the provided document. * * This object should have the same structure as [Sentiment]{@link google.cloud.language.v1.Sentiment} * @@ -149,7 +151,10 @@ const Entity = { // This is for documentation. Actual contents will be loaded by gRPC. /** - * 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 {number} * @memberof google.cloud.language.v1 @@ -182,42 +187,67 @@ const Entity = { 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

+ * The metadata lists the phone number, formatted according to local + * convention, plus whichever additional elements appear in the text: */ PHONE_NUMBER: 9, /** - * Address + * Address

+ * The metadata identifies the street number and locality plus whichever + * additional elements appear in the text: */ ADDRESS: 10, /** - * Date + * Date

+ * The metadata identifies the components of the date: */ DATE: 11, /** - * Number + * Number

+ * The metadata is the number itself. */ NUMBER: 12, /** - * Price + * Price

+ * The metadata identifies the value and currency. */ PRICE: 13 } @@ -1336,9 +1366,9 @@ const DependencyEdge = { * * @property {Object} sentiment * For calls to AnalyzeEntitySentiment or if - * 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 is set to + * true, this field will contain the sentiment expressed for this mention of + * the entity in the provided document. * * This object should have the same structure as [Sentiment]{@link google.cloud.language.v1.Sentiment} * @@ -1382,9 +1412,7 @@ const EntityMention = { * * @property {number} beginOffset * The API calculates the beginning offset of the content in the original - * document according to the - * EncodingType specified in the API - * request. + * document according to the EncodingType specified in the API request. * * @typedef TextSpan * @memberof google.cloud.language.v1 @@ -1445,8 +1473,7 @@ const AnalyzeSentimentRequest = { * @property {string} language * 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 field - * for more details. + * See Document.language field for more details. * * @property {Object[]} sentences * The sentiment for all the sentences in the document. @@ -1493,8 +1520,7 @@ const AnalyzeEntitySentimentRequest = { * @property {string} language * 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 field - * for more details. + * See Document.language field for more details. * * @typedef AnalyzeEntitySentimentResponse * @memberof google.cloud.language.v1 @@ -1536,8 +1562,7 @@ const AnalyzeEntitiesRequest = { * @property {string} language * 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 field - * for more details. + * See Document.language field for more details. * * @typedef AnalyzeEntitiesResponse * @memberof google.cloud.language.v1 @@ -1584,8 +1609,7 @@ const AnalyzeSyntaxRequest = { * @property {string} language * 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 field - * for more details. + * See Document.language field for more details. * * @typedef AnalyzeSyntaxResponse * @memberof google.cloud.language.v1 @@ -1713,8 +1737,7 @@ const AnnotateTextRequest = { * @property {string} language * 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 field - * for more details. + * See Document.language field for more details. * * @property {Object[]} categories * Categories identified in the input document. diff --git a/packages/google-cloud-language/src/v1/language_service_client.js b/packages/google-cloud-language/src/v1/language_service_client.js index c06ac2f8de8..994ea7d362a 100644 --- a/packages/google-cloud-language/src/v1/language_service_client.js +++ b/packages/google-cloud-language/src/v1/language_service_client.js @@ -291,10 +291,8 @@ class LanguageServiceClient { } /** - * Finds entities, similar to - * AnalyzeEntities - * in the text and analyzes sentiment associated with each entity and its - * mentions. + * Finds entities, similar to AnalyzeEntities in the text and analyzes + * sentiment associated with each entity and its mentions. * * @param {Object} request * The request object that will be sent. diff --git a/packages/google-cloud-language/synth.metadata b/packages/google-cloud-language/synth.metadata index 3642d502c07..81398c4b8a7 100644 --- a/packages/google-cloud-language/synth.metadata +++ b/packages/google-cloud-language/synth.metadata @@ -1,19 +1,19 @@ { - "updateTime": "2019-03-22T11:16:51.183804Z", + "updateTime": "2019-04-04T11:16:12.440846Z", "sources": [ { "generator": { "name": "artman", - "version": "0.16.18", - "dockerImage": "googleapis/artman@sha256:e8ac9200640e76d54643f370db71a1556bf254f565ce46b45a467bbcbacbdb37" + "version": "0.16.23", + "dockerImage": "googleapis/artman@sha256:f3a3f88000dc1cd1b4826104c5574aa5c534f6793fbf66e888d11c0d7ef5762e" } }, { "git": { "name": "googleapis", "remote": "https://github.com/googleapis/googleapis.git", - "sha": "e2a116ac081210002ec2e634f1f840a453ebd182", - "internalRef": "239695990" + "sha": "04193ea2f8121388c998ab49c382f2c03417dcce", + "internalRef": "241828309" } }, {