docs: more detailed docs on APIs such as Environment, Intents, Sessio…

…ns. (#658)

PiperOrigin-RevId: 323086730

Source-Author: Google APIs <noreply@google.com>
Source-Date: Fri Jul 24 15:42:41 2020 -0700
Source-Repo: googleapis/googleapis
Source-Sha: a6b2dac798ed266136e990a2319b2e2e96f3bdbe
Source-Link: googleapis/googleapis@a6b2dac

packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2/agent.proto

@@ -173,8 +173,7 @@ service Agents {
 // conversations required for your system.
 //
 // For more information about agents, see the
-// [Agents
-// documentation](https://cloud.google.com/dialogflow/docs/agents-overview).
+// [Agent guide](https://cloud.google.com/dialogflow/docs/agents-overview).
 message Agent {
   option (google.api.resource) = {
     type: "dialogflow.googleapis.com/Agent"

packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2/context.proto

@@ -32,24 +32,7 @@ option java_outer_classname = "ContextProto";
 option java_package = "com.google.cloud.dialogflow.v2";
 option objc_class_prefix = "DF";
 
-// A context represents additional information included with user input or with
-// an intent returned by the Dialogflow API. Contexts are helpful for
-// differentiating user input which may be vague or have a different meaning
-// depending on additional details from your application such as user setting
-// and preferences, previous user input, where the user is in your application,
-// geographic location, and so on.
-//
-// You can include contexts as input parameters of a
-// [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or
-// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) request,
-// or as output contexts included in the returned intent.
-// Contexts expire when an intent is matched, after the number of `DetectIntent`
-// requests specified by the `lifespan_count` parameter, or after 20 minutes
-// if no intents are matched for a `DetectIntent` request.
-//
-// For more information about contexts, see the
-// [Dialogflow
-// documentation](https://cloud.google.com/dialogflow/docs/contexts-overview).
+// Service for managing [Contexts][google.cloud.dialogflow.v2.Context].
 service Contexts {
   option (google.api.default_host) = "dialogflow.googleapis.com";
   option (google.api.oauth_scopes) =
@@ -129,7 +112,21 @@ service Contexts {
   }
 }
 
-// Represents a context.
+// Dialogflow contexts are similar to natural language context. If a person says
+// to you "they are orange", you need context in order to understand what "they"
+// is referring to. Similarly, for Dialogflow to handle an end-user expression
+// like that, it needs to be provided with context in order to correctly match
+// an intent.
+//
+// Using contexts, you can control the flow of a conversation. You can configure
+// contexts for an intent by setting input and output contexts, which are
+// identified by string names. When an intent is matched, any configured output
+// contexts for that intent become active. While any contexts are active,
+// Dialogflow is more likely to match intents that are configured with input
+// contexts that correspond to the currently active contexts.
+//
+// For more information about context, see the
+// [Contexts guide](https://cloud.google.com/dialogflow/docs/contexts-overview).
 message Context {
   option (google.api.resource) = {
     type: "dialogflow.googleapis.com/Context"

packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2/entity_type.proto

@@ -32,34 +32,7 @@ option java_outer_classname = "EntityTypeProto";
 option java_package = "com.google.cloud.dialogflow.v2";
 option objc_class_prefix = "DF";
 
-// Entities are extracted from user input and represent parameters that are
-// meaningful to your application. For example, a date range, a proper name
-// such as a geographic location or landmark, and so on. Entities represent
-// actionable data for your application.
-//
-// When you define an entity, you can also include synonyms that all map to
-// that entity. For example, "soft drink", "soda", "pop", and so on.
-//
-// There are three types of entities:
-//
-// *   **System** - entities that are defined by the Dialogflow API for common
-//     data types such as date, time, currency, and so on. A system entity is
-//     represented by the `EntityType` type.
-//
-// *   **Custom** - entities that are defined by you that represent
-//     actionable data that is meaningful to your application. For example,
-//     you could define a `pizza.sauce` entity for red or white pizza sauce,
-//     a `pizza.cheese` entity for the different types of cheese on a pizza,
-//     a `pizza.topping` entity for different toppings, and so on. A custom
-//     entity is represented by the `EntityType` type.
-//
-// *   **User** - entities that are built for an individual user such as
-//     favorites, preferences, playlists, and so on. A user entity is
-//     represented by the [SessionEntityType][google.cloud.dialogflow.v2.SessionEntityType] type.
-//
-// For more information about entity types, see the
-// [Dialogflow
-// documentation](https://cloud.google.com/dialogflow/docs/entities-overview).
+// Service for managing [EntityTypes][google.cloud.dialogflow.v2.EntityType].
 service EntityTypes {
   option (google.api.default_host) = "dialogflow.googleapis.com";
   option (google.api.oauth_scopes) =
@@ -194,9 +167,18 @@ service EntityTypes {
   }
 }
 
-// Represents an entity type.
-// Entity types serve as a tool for extracting parameter values from natural
-// language queries.
+// Each intent parameter has a type, called the entity type, which dictates
+// exactly how data from an end-user expression is extracted.
+//
+// Dialogflow provides predefined system entities that can match many common
+// types of data. For example, there are system entities for matching dates,
+// times, colors, email addresses, and so on. You can also create your own
+// custom entities for matching custom data. For example, you could define a
+// vegetable entity that can match the types of vegetables available for
+// purchase with a grocery store agent.
+//
+// For more information, see the
+// [Entity guide](https://cloud.google.com/dialogflow/docs/entities-overview).
 message EntityType {
   option (google.api.resource) = {
     type: "dialogflow.googleapis.com/EntityType"

packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2/environment.proto

@@ -32,7 +32,7 @@ option java_outer_classname = "EnvironmentProto";
 option java_package = "com.google.cloud.dialogflow.v2";
 option objc_class_prefix = "DF";
 
-// Manages agent environments.
+// Service for managing [Environments][google.cloud.dialogflow.v2.Environment].
 service Environments {
   option (google.api.default_host) = "dialogflow.googleapis.com";
   option (google.api.oauth_scopes) =
@@ -47,7 +47,24 @@ service Environments {
   }
 }
 
-// Represents an agent environment.
+// You can create multiple versions of your agent and publish them to separate
+// environments.
+//
+// When you edit an agent, you are editing the draft agent. At any point, you
+// can save the draft agent as an agent version, which is an immutable snapshot
+// of your agent.
+//
+// When you save the draft agent, it is published to the default environment.
+// When you create agent versions, you can publish them to custom environments.
+// You can create a variety of custom environments for:
+//
+// - testing
+// - development
+// - production
+// - etc.
+//
+// For more information, see the [versions and environments
+// guide](https://cloud.google.com/dialogflow/docs/agents-versions).
 message Environment {
   option (google.api.resource) = {
     type: "dialogflow.googleapis.com/Environment"

packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2/intent.proto

@@ -36,38 +36,7 @@ option java_outer_classname = "IntentProto";
 option java_package = "com.google.cloud.dialogflow.v2";
 option objc_class_prefix = "DF";
 
-// An intent represents a mapping between input from a user and an action to
-// be taken by your application. When you pass user input to the
-// [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or
-// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) method, the
-// Dialogflow API analyzes the input and searches
-// for a matching intent. If no match is found, the Dialogflow API returns a
-// fallback intent (`is_fallback` = true).
-//
-// You can provide additional information for the Dialogflow API to use to
-// match user input to an intent by adding the following to your intent.
-//
-// *   **Contexts** - provide additional context for intent analysis. For
-//     example, if an intent is related to an object in your application that
-//     plays music, you can provide a context to determine when to match the
-//     intent if the user input is "turn it off". You can include a context
-//     that matches the intent when there is previous user input of
-//     "play music", and not when there is previous user input of
-//     "turn on the light".
-//
-// *   **Events** - allow for matching an intent by using an event name
-//     instead of user input. Your application can provide an event name and
-//     related parameters to the Dialogflow API to match an intent. For
-//     example, when your application starts, you can send a welcome event
-//     with a user name parameter to the Dialogflow API to match an intent with
-//     a personalized welcome message for the user.
-//
-// *   **Training phrases** - provide examples of user input to train the
-//     Dialogflow API agent to better match intents.
-//
-// For more information about intents, see the
-// [Dialogflow
-// documentation](https://cloud.google.com/dialogflow/docs/intents-overview).
+// Service for managing [Intents][google.cloud.dialogflow.v2.Intent].
 service Intents {
   option (google.api.default_host) = "dialogflow.googleapis.com";
   option (google.api.oauth_scopes) =
@@ -152,9 +121,15 @@ service Intents {
   }
 }
 
-// Represents an intent.
-// Intents convert a number of user expressions or patterns into an action. An
-// action is an extraction of a user command or sentence semantics.
+// An intent categorizes an end-user's intention for one conversation turn. For
+// each agent, you define many intents, where your combined intents can handle a
+// complete conversation. When an end-user writes or says something, referred to
+// as an end-user expression or end-user input, Dialogflow matches the end-user
+// input to the best intent in your agent. Matching an intent is also known as
+// intent classification.
+//
+// For more information, see the [intent
+// guide](https://cloud.google.com/dialogflow/docs/intents-overview).
 message Intent {
   option (google.api.resource) = {
     type: "dialogflow.googleapis.com/Intent"

packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2/session.proto

@@ -43,10 +43,10 @@ option (google.api.resource_definition) = {
   pattern: "projects/{project}/agent/environments/{environment}/users/{user}/sessions/{session}"
 };
 
-// A session represents an interaction with a user. You retrieve user input
-// and pass it to the [DetectIntent][google.cloud.dialogflow.v2.Sessions.DetectIntent] (or
-// [StreamingDetectIntent][google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent]) method to determine
-// user intent and respond.
+// A service used for session interactions.
+//
+// For more information, see the [API interactions
+// guide](https://cloud.google.com/dialogflow/docs/api-overview).
 service Sessions {
   option (google.api.default_host) = "dialogflow.googleapis.com";
   option (google.api.oauth_scopes) =
@@ -87,6 +87,9 @@ message DetectIntentRequest {
   // `User Id`. They can be a random number or some type of user and session
   // identifiers (preferably hashed). The length of the `Session ID` and
   // `User ID` must not exceed 36 characters.
+  //
+  // For more information, see the [API interactions
+  // guide](https://cloud.google.com/dialogflow/docs/api-overview).
   string session = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -362,6 +365,9 @@ message StreamingDetectIntentRequest {
   // `User Id`. They can be a random number or some type of user and session
   // identifiers (preferably hashed). The length of the `Session ID` and
   // `User ID` must not exceed 36 characters.
+  //
+  // For more information, see the [API interactions
+  // guide](https://cloud.google.com/dialogflow/docs/api-overview).
   string session = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -591,8 +597,16 @@ message SentimentAnalysisRequestConfig {
   bool analyze_query_text_sentiment = 1;
 }
 
-// The result of sentiment analysis as configured by
-// `sentiment_analysis_request_config`.
+// The result of sentiment analysis. Sentiment analysis inspects user input
+// and identifies the prevailing subjective opinion, especially to determine a
+// user's attitude as positive, negative, or neutral.
+// For [Participants.AnalyzeContent][google.cloud.dialogflow.v2.Participants.AnalyzeContent], it needs to be configured in
+// [DetectIntentRequest.query_params][google.cloud.dialogflow.v2.DetectIntentRequest.query_params]. For
+// [Participants.StreamingAnalyzeContent][google.cloud.dialogflow.v2.Participants.StreamingAnalyzeContent], it needs to be configured in
+// [StreamingDetectIntentRequest.query_params][google.cloud.dialogflow.v2.StreamingDetectIntentRequest.query_params].
+// And for [Participants.AnalyzeContent][google.cloud.dialogflow.v2.Participants.AnalyzeContent] and
+// [Participants.StreamingAnalyzeContent][google.cloud.dialogflow.v2.Participants.StreamingAnalyzeContent], it needs to be configured in
+// [ConversationProfile.human_agent_assistant_config][google.cloud.dialogflow.v2.ConversationProfile.human_agent_assistant_config]
 message SentimentAnalysisResult {
   // The sentiment analysis result for `query_text`.
   Sentiment query_text_sentiment = 1;

packages/google-cloud-dialogflow/protos/google/cloud/dialogflow/v2/session_entity_type.proto

@@ -32,23 +32,7 @@ option java_outer_classname = "SessionEntityTypeProto";
 option java_package = "com.google.cloud.dialogflow.v2";
 option objc_class_prefix = "DF";
 
-// Entities are extracted from user input and represent parameters that are
-// meaningful to your application. For example, a date range, a proper name
-// such as a geographic location or landmark, and so on. Entities represent
-// actionable data for your application.
-//
-// Session entity types are referred to as **User** entity types and are
-// entities that are built for an individual user such as
-// favorites, preferences, playlists, and so on. You can redefine a session
-// entity type at the session level.
-//
-// Session entity methods do not work with Google Assistant integration.
-// Contact Dialogflow support if you need to use session entities
-// with Google Assistant integration.
-//
-// For more information about entity types, see the
-// [Dialogflow
-// documentation](https://cloud.google.com/dialogflow/docs/entities-overview).
+// Service for managing [SessionEntityTypes][google.cloud.dialogflow.v2.SessionEntityType].
 service SessionEntityTypes {
   option (google.api.default_host) = "dialogflow.googleapis.com";
   option (google.api.oauth_scopes) =
@@ -139,13 +123,14 @@ service SessionEntityTypes {
   }
 }
 
-// Represents a session entity type.
-//
-// Extends or replaces a custom entity type at the user session level (we
-// refer to the entity types defined at the agent level as "custom entity
-// types").
+// A session represents a conversation between a Dialogflow agent and an
+// end-user. You can create special entities, called session entities, during a
+// session. Session entities can extend or replace custom entity types and only
+// exist during the session that they were created for. All session data,
+// including session entities, is stored by Dialogflow for 20 minutes.
 //
-// Note: session entity types apply to all queries, regardless of the language.
+// For more information, see the [session entity
+// guide](https://cloud.google.com/dialogflow/docs/entities-session).
 message SessionEntityType {
   option (google.api.resource) = {
     type: "dialogflow.googleapis.com/SessionEntityType"

packages/google-cloud-dialogflow/src/v2/contexts_client.ts

@@ -35,24 +35,7 @@ import * as gapicConfig from './contexts_client_config.json';
 const version = require('../../../package.json').version;
 
 /**
- *  A context represents additional information included with user input or with
- *  an intent returned by the Dialogflow API. Contexts are helpful for
- *  differentiating user input which may be vague or have a different meaning
- *  depending on additional details from your application such as user setting
- *  and preferences, previous user input, where the user is in your application,
- *  geographic location, and so on.
- *
- *  You can include contexts as input parameters of a
- *  {@link google.cloud.dialogflow.v2.Sessions.DetectIntent|DetectIntent} (or
- *  {@link google.cloud.dialogflow.v2.Sessions.StreamingDetectIntent|StreamingDetectIntent}) request,
- *  or as output contexts included in the returned intent.
- *  Contexts expire when an intent is matched, after the number of `DetectIntent`
- *  requests specified by the `lifespan_count` parameter, or after 20 minutes
- *  if no intents are matched for a `DetectIntent` request.
- *
- *  For more information about contexts, see the
- *  [Dialogflow
- *  documentation](https://cloud.google.com/dialogflow/docs/contexts-overview).
+ *  Service for managing {@link google.cloud.dialogflow.v2.Context|Contexts}.
  * @class
  * @memberof v2
  */

packages/google-cloud-dialogflow/src/v2/entity_types_client.ts

@@ -36,34 +36,7 @@ import {operationsProtos} from 'google-gax';
 const version = require('../../../package.json').version;
 
 /**
- *  Entities are extracted from user input and represent parameters that are
- *  meaningful to your application. For example, a date range, a proper name
- *  such as a geographic location or landmark, and so on. Entities represent
- *  actionable data for your application.
- *
- *  When you define an entity, you can also include synonyms that all map to
- *  that entity. For example, "soft drink", "soda", "pop", and so on.
- *
- *  There are three types of entities:
- *
- *  *   **System** - entities that are defined by the Dialogflow API for common
- *      data types such as date, time, currency, and so on. A system entity is
- *      represented by the `EntityType` type.
- *
- *  *   **Custom** - entities that are defined by you that represent
- *      actionable data that is meaningful to your application. For example,
- *      you could define a `pizza.sauce` entity for red or white pizza sauce,
- *      a `pizza.cheese` entity for the different types of cheese on a pizza,
- *      a `pizza.topping` entity for different toppings, and so on. A custom
- *      entity is represented by the `EntityType` type.
- *
- *  *   **User** - entities that are built for an individual user such as
- *      favorites, preferences, playlists, and so on. A user entity is
- *      represented by the {@link google.cloud.dialogflow.v2.SessionEntityType|SessionEntityType} type.
- *
- *  For more information about entity types, see the
- *  [Dialogflow
- *  documentation](https://cloud.google.com/dialogflow/docs/entities-overview).
+ *  Service for managing {@link google.cloud.dialogflow.v2.EntityType|EntityTypes}.
  * @class
  * @memberof v2
  */

packages/google-cloud-dialogflow/src/v2/environments_client.ts

@@ -35,7 +35,7 @@ import * as gapicConfig from './environments_client_config.json';
 const version = require('../../../package.json').version;
 
 /**
- *  Manages agent environments.
+ *  Service for managing {@link google.cloud.dialogflow.v2.Environment|Environments}.
  * @class
  * @memberof v2
  */