docs: more detailed docs on APIs such as Environment, and deleting No…

…de 8 tests (#650)

* changes without context

        autosynth cannot find the source of changes triggered by earlier changes in this
        repository, or by version upgrades to tools such as linters.

* docs: more detailed docs on APIs such as Environment, Intents, Sessions.

PiperOrigin-RevId: 321243814

Source-Author: Google APIs <noreply@google.com>
Source-Date: Tue Jul 14 15:08:49 2020 -0700
Source-Repo: googleapis/googleapis
Source-Sha: 84ebe7c62f4c0875e001752fa84e87e629a1d418
Source-Link: googleapis/googleapis@84ebe7c

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

@@ -34,34 +34,7 @@ option java_outer_classname = "AgentProto";
 option java_package = "com.google.cloud.dialogflow.v2beta1";
 option objc_class_prefix = "DF";
 
-// Agents are best described as Natural Language Understanding (NLU) modules
-// that transform user requests into actionable data. You can include agents
-// in your app, product, or service to determine user intent and respond to the
-// user in a natural way.
-//
-// After you create an agent, you can add [Intents][google.cloud.dialogflow.v2beta1.Intents], [Contexts][google.cloud.dialogflow.v2beta1.Contexts],
-// [Entity Types][google.cloud.dialogflow.v2beta1.EntityTypes], [Webhooks][google.cloud.dialogflow.v2beta1.WebhookRequest], and so on to
-// manage the flow of a conversation and match user input to predefined intents
-// and actions.
-//
-// You can create an agent using both Dialogflow Standard Edition and
-// Dialogflow Enterprise Edition. For details, see
-// [Dialogflow
-// Editions](https://cloud.google.com/dialogflow/docs/editions).
-//
-// You can save your agent for backup or versioning by exporting the agent by
-// using the [ExportAgent][google.cloud.dialogflow.v2beta1.Agents.ExportAgent] method. You can import a saved
-// agent by using the [ImportAgent][google.cloud.dialogflow.v2beta1.Agents.ImportAgent] method.
-//
-// Dialogflow provides several
-// [prebuilt
-// agents](https://cloud.google.com/dialogflow/docs/agents-prebuilt)
-// for common conversation scenarios such as determining a date and time,
-// converting currency, and so on.
-//
-// For more information about agents, see the
-// [Dialogflow
-// documentation](https://cloud.google.com/dialogflow/docs/agents-overview).
+// Service for managing [Agents][google.cloud.dialogflow.v2beta1.Agent].
 service Agents {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
@@ -225,7 +198,15 @@ service Agents {
  }
 }
 
-// Represents a conversational agent.
+// A Dialogflow agent is a virtual agent that handles conversations with your
+// end-users. It is a natural language understanding module that understands the
+// nuances of human language. Dialogflow translates end-user text or audio
+// during a conversation to structured data that your apps and services can
+// understand. You design and build a Dialogflow agent to handle the types of
+// conversations required for your system.
+//
+// For more information about agents, see the
+// [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/v2beta1/context.proto

@@ -32,24 +32,7 @@ option java_outer_classname = "ContextProto";
 option java_package = "com.google.cloud.dialogflow.v2beta1";
 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.v2beta1.Sessions.DetectIntent] (or
-// [StreamingDetectIntent][google.cloud.dialogflow.v2beta1.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.v2beta1.Context].
 service Contexts {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
@@ -169,7 +152,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/v2beta1/document.proto

@@ -35,7 +35,7 @@ option java_outer_classname = "DocumentProto";
 option java_package = "com.google.cloud.dialogflow.v2beta1";
 option objc_class_prefix = "DF";
 
-// Manages documents of a knowledge base.
+// Service for managing knowledge [Documents][google.cloud.dialogflow.v2beta1.Document].
 service Documents {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
@@ -151,7 +151,10 @@ service Documents {
  }
 }
 
-// A document resource.
+// A knowledge document to be used by a [KnowledgeBase][google.cloud.dialogflow.v2beta1.KnowledgeBase].
+//
+// For more information, see the [knowledge base
+// guide](https://cloud.google.com/dialogflow/docs/how/knowledge-bases).
 //
 // Note: The `projects.agent.knowledgeBases.documents` resource is deprecated;
 // only use `projects.knowledgeBases.documents`.
@@ -279,12 +282,12 @@ message ListDocumentsRequest {
  }
  ];
 
- // Optional. The maximum number of items to return in a single page. By
+ // The maximum number of items to return in a single page. By
  // default 10 and at most 100.
- int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
+ int32 page_size = 2;
 
- // Optional. The next_page_token value returned from a previous list request.
- string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
+ // The next_page_token value returned from a previous list request.
+ string page_token = 3;
 }
 
 // Response message for [Documents.ListDocuments][google.cloud.dialogflow.v2beta1.Documents.ListDocuments].

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

@@ -32,34 +32,7 @@ option java_outer_classname = "EntityTypeProto";
 option java_package = "com.google.cloud.dialogflow.v2beta1";
 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.v2beta1.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.v2beta1.EntityType].
 service EntityTypes {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
@@ -226,9 +199,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/v2beta1/environment.proto

@@ -33,7 +33,7 @@ option java_outer_classname = "EnvironmentProto";
 option java_package = "com.google.cloud.dialogflow.v2beta1";
 option objc_class_prefix = "DF";
 
-// Manages agent environments.
+// Service for managing [Environments][google.cloud.dialogflow.v2beta1.Environment].
 service Environments {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
@@ -51,7 +51,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/v2beta1/intent.proto

@@ -36,38 +36,7 @@ option java_outer_classname = "IntentProto";
 option java_package = "com.google.cloud.dialogflow.v2beta1";
 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.v2beta1.Sessions.DetectIntent] (or
-// [StreamingDetectIntent][google.cloud.dialogflow.v2beta1.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.v2beta1.Intent].
 service Intents {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
@@ -176,9 +145,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/v2beta1/knowledge_base.proto

@@ -31,9 +31,7 @@ option java_outer_classname = "KnowledgeBaseProto";
 option java_package = "com.google.cloud.dialogflow.v2beta1";
 option objc_class_prefix = "DF";
 
-// Manages knowledge bases.
-//
-// Allows users to setup and maintain knowledge bases with their knowledge data.
+// Service for managing [KnowledgeBases][google.cloud.dialogflow.v2beta1.KnowledgeBase].
 service KnowledgeBases {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
@@ -115,7 +113,13 @@ service KnowledgeBases {
  }
 }
 
-// Represents knowledge base resource.
+// A knowledge base represents a collection of knowledge documents that you
+// provide to Dialogflow. Your knowledge documents contain information that may
+// be useful during conversations with end-users. Some Dialogflow features use
+// knowledge bases when looking for a response to an end-user input.
+//
+// For more information, see the [knowledge base
+// guide](https://cloud.google.com/dialogflow/docs/how/knowledge-bases).
 //
 // Note: The `projects.agent.knowledgeBases` resource is deprecated;
 // only use `projects.knowledgeBases`.

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

@@ -45,10 +45,10 @@ option (google.api.resource_definition) = {
  pattern: "projects/{project}/locations/{location}/agent/sessions/{session}"
 };
 
-// A session represents an interaction with a user. You retrieve user input
-// and pass it to the [DetectIntent][google.cloud.dialogflow.v2beta1.Sessions.DetectIntent] (or
-// [StreamingDetectIntent][google.cloud.dialogflow.v2beta1.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) =
@@ -97,6 +97,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.resource_reference) = {
  type: "dialogflow.googleapis.com/Session"
  }];
@@ -464,6 +467,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;
 
  // The parameters of this query.
@@ -715,8 +721,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.v2beta1.Participants.AnalyzeContent], it needs to be configured in
+// [DetectIntentRequest.query_params][google.cloud.dialogflow.v2beta1.DetectIntentRequest.query_params]. For
+// [Participants.StreamingAnalyzeContent][google.cloud.dialogflow.v2beta1.Participants.StreamingAnalyzeContent], it needs to be configured in
+// [StreamingDetectIntentRequest.query_params][google.cloud.dialogflow.v2beta1.StreamingDetectIntentRequest.query_params].
+// And for [Participants.AnalyzeContent][google.cloud.dialogflow.v2beta1.Participants.AnalyzeContent] and
+// [Participants.StreamingAnalyzeContent][google.cloud.dialogflow.v2beta1.Participants.StreamingAnalyzeContent], it needs to be configured in
+// [ConversationProfile.human_agent_assistant_config][google.cloud.dialogflow.v2beta1.ConversationProfile.human_agent_assistant_config]
 message SentimentAnalysisResult {
  // The sentiment analysis result for `query_text`.
  Sentiment query_text_sentiment = 1;