Skip to content

Commit

Permalink
fix: improve docstrings, and add more field validation (#224)
Browse files Browse the repository at this point in the history 
fix: improve docstrings, and add more field validation
  • Loading branch information
@yoshi-automation @JustinBeckwith
yoshi-automation authored and JustinBeckwith committed Apr 4, 2019
1 parent d6f1688 commit 4311718
Show file tree
Hide file tree
Showing 4 changed files with 147 additions and 90 deletions.
134 changes: 85 additions & 49 deletions packages/google-cloud-language/protos/google/cloud/language/v1/language_service.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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,
Expand All @@ -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";
}
}

Expand Down Expand Up @@ -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.
Expand All @@ -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;
Expand All @@ -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;
}

Expand All @@ -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.
Expand All @@ -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;
}

Expand Down Expand Up @@ -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;
}

Expand All @@ -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;
}

Expand All @@ -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;
Expand All @@ -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.
Expand All @@ -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;
Expand All @@ -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;
Expand All @@ -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;
Expand All @@ -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.
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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.
Expand Down
Loading

0 comments on commit 4311718

Please sign in to comment.