docs: update the doc on diagnostic info (#477)

- [ ] Regenerate this pull request now.

PiperOrigin-RevId: 446890999

Source-Link: googleapis/googleapis@044c518

Source-Link: https://github.com/googleapis/googleapis-gen/commit/770df39bd68400a84c0bb256c3c2fb7d65d649d5
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNzcwZGYzOWJkNjg0MDBhODRjMGJiMjU2YzNjMmZiN2Q2NWQ2NDlkNSJ9

java-dialogflow-cx/proto-google-cloud-dialogflow-cx-v3/src/main/java/com/google/cloud/dialogflow/cx/v3/QueryResult.java

@@ -1269,8 +1269,20 @@ public com.google.cloud.dialogflow.cx.v3.MatchOrBuilder getMatchOrBuilder() {
    *
    * <pre>
    * The free-form diagnostic info. For example, this field could contain
-   * webhook call latency. The string keys of the Struct's fields map can change
-   * without notice.
+   * webhook call latency. The fields of this data can change without notice,
+   * so you should not write code that depends on its structure.
+   * One of the fields is called "Alternative Matched Intents", which may
+   * aid with debugging. The following describes these intent results:
+   * - The list is empty if no intent was matched to end-user input.
+   * - Only intents that are referenced in the currently active flow are
+   *   included.
+   * - The matched intent is included.
+   * - Other intents that could have matched end-user input, but did not match
+   *   because they are referenced by intent routes that are out of
+   *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+   *   are included.
+   * - Other intents referenced by intent routes in scope that matched end-user
+   *   input, but had a lower confidence score.
    * </pre>
    *
    * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -1286,8 +1298,20 @@ public boolean hasDiagnosticInfo() {
    *
    * <pre>
    * The free-form diagnostic info. For example, this field could contain
-   * webhook call latency. The string keys of the Struct's fields map can change
-   * without notice.
+   * webhook call latency. The fields of this data can change without notice,
+   * so you should not write code that depends on its structure.
+   * One of the fields is called "Alternative Matched Intents", which may
+   * aid with debugging. The following describes these intent results:
+   * - The list is empty if no intent was matched to end-user input.
+   * - Only intents that are referenced in the currently active flow are
+   *   included.
+   * - The matched intent is included.
+   * - Other intents that could have matched end-user input, but did not match
+   *   because they are referenced by intent routes that are out of
+   *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+   *   are included.
+   * - Other intents referenced by intent routes in scope that matched end-user
+   *   input, but had a lower confidence score.
    * </pre>
    *
    * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -1305,8 +1329,20 @@ public com.google.protobuf.Struct getDiagnosticInfo() {
    *
    * <pre>
    * The free-form diagnostic info. For example, this field could contain
-   * webhook call latency. The string keys of the Struct's fields map can change
-   * without notice.
+   * webhook call latency. The fields of this data can change without notice,
+   * so you should not write code that depends on its structure.
+   * One of the fields is called "Alternative Matched Intents", which may
+   * aid with debugging. The following describes these intent results:
+   * - The list is empty if no intent was matched to end-user input.
+   * - Only intents that are referenced in the currently active flow are
+   *   included.
+   * - The matched intent is included.
+   * - Other intents that could have matched end-user input, but did not match
+   *   because they are referenced by intent routes that are out of
+   *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+   *   are included.
+   * - Other intents referenced by intent routes in scope that matched end-user
+   *   input, but had a lower confidence score.
    * </pre>
    *
    * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -5205,8 +5241,20 @@ public com.google.cloud.dialogflow.cx.v3.MatchOrBuilder getMatchOrBuilder() {
      *
      * <pre>
      * The free-form diagnostic info. For example, this field could contain
-     * webhook call latency. The string keys of the Struct's fields map can change
-     * without notice.
+     * webhook call latency. The fields of this data can change without notice,
+     * so you should not write code that depends on its structure.
+     * One of the fields is called "Alternative Matched Intents", which may
+     * aid with debugging. The following describes these intent results:
+     * - The list is empty if no intent was matched to end-user input.
+     * - Only intents that are referenced in the currently active flow are
+     *   included.
+     * - The matched intent is included.
+     * - Other intents that could have matched end-user input, but did not match
+     *   because they are referenced by intent routes that are out of
+     *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+     *   are included.
+     * - Other intents referenced by intent routes in scope that matched end-user
+     *   input, but had a lower confidence score.
      * </pre>
      *
      * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -5221,8 +5269,20 @@ public boolean hasDiagnosticInfo() {
      *
      * <pre>
      * The free-form diagnostic info. For example, this field could contain
-     * webhook call latency. The string keys of the Struct's fields map can change
-     * without notice.
+     * webhook call latency. The fields of this data can change without notice,
+     * so you should not write code that depends on its structure.
+     * One of the fields is called "Alternative Matched Intents", which may
+     * aid with debugging. The following describes these intent results:
+     * - The list is empty if no intent was matched to end-user input.
+     * - Only intents that are referenced in the currently active flow are
+     *   included.
+     * - The matched intent is included.
+     * - Other intents that could have matched end-user input, but did not match
+     *   because they are referenced by intent routes that are out of
+     *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+     *   are included.
+     * - Other intents referenced by intent routes in scope that matched end-user
+     *   input, but had a lower confidence score.
      * </pre>
      *
      * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -5243,8 +5303,20 @@ public com.google.protobuf.Struct getDiagnosticInfo() {
      *
      * <pre>
      * The free-form diagnostic info. For example, this field could contain
-     * webhook call latency. The string keys of the Struct's fields map can change
-     * without notice.
+     * webhook call latency. The fields of this data can change without notice,
+     * so you should not write code that depends on its structure.
+     * One of the fields is called "Alternative Matched Intents", which may
+     * aid with debugging. The following describes these intent results:
+     * - The list is empty if no intent was matched to end-user input.
+     * - Only intents that are referenced in the currently active flow are
+     *   included.
+     * - The matched intent is included.
+     * - Other intents that could have matched end-user input, but did not match
+     *   because they are referenced by intent routes that are out of
+     *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+     *   are included.
+     * - Other intents referenced by intent routes in scope that matched end-user
+     *   input, but had a lower confidence score.
      * </pre>
      *
      * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -5267,8 +5339,20 @@ public Builder setDiagnosticInfo(com.google.protobuf.Struct value) {
      *
      * <pre>
      * The free-form diagnostic info. For example, this field could contain
-     * webhook call latency. The string keys of the Struct's fields map can change
-     * without notice.
+     * webhook call latency. The fields of this data can change without notice,
+     * so you should not write code that depends on its structure.
+     * One of the fields is called "Alternative Matched Intents", which may
+     * aid with debugging. The following describes these intent results:
+     * - The list is empty if no intent was matched to end-user input.
+     * - Only intents that are referenced in the currently active flow are
+     *   included.
+     * - The matched intent is included.
+     * - Other intents that could have matched end-user input, but did not match
+     *   because they are referenced by intent routes that are out of
+     *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+     *   are included.
+     * - Other intents referenced by intent routes in scope that matched end-user
+     *   input, but had a lower confidence score.
      * </pre>
      *
      * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -5288,8 +5372,20 @@ public Builder setDiagnosticInfo(com.google.protobuf.Struct.Builder builderForVa
      *
      * <pre>
      * The free-form diagnostic info. For example, this field could contain
-     * webhook call latency. The string keys of the Struct's fields map can change
-     * without notice.
+     * webhook call latency. The fields of this data can change without notice,
+     * so you should not write code that depends on its structure.
+     * One of the fields is called "Alternative Matched Intents", which may
+     * aid with debugging. The following describes these intent results:
+     * - The list is empty if no intent was matched to end-user input.
+     * - Only intents that are referenced in the currently active flow are
+     *   included.
+     * - The matched intent is included.
+     * - Other intents that could have matched end-user input, but did not match
+     *   because they are referenced by intent routes that are out of
+     *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+     *   are included.
+     * - Other intents referenced by intent routes in scope that matched end-user
+     *   input, but had a lower confidence score.
      * </pre>
      *
      * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -5316,8 +5412,20 @@ public Builder mergeDiagnosticInfo(com.google.protobuf.Struct value) {
      *
      * <pre>
      * The free-form diagnostic info. For example, this field could contain
-     * webhook call latency. The string keys of the Struct's fields map can change
-     * without notice.
+     * webhook call latency. The fields of this data can change without notice,
+     * so you should not write code that depends on its structure.
+     * One of the fields is called "Alternative Matched Intents", which may
+     * aid with debugging. The following describes these intent results:
+     * - The list is empty if no intent was matched to end-user input.
+     * - Only intents that are referenced in the currently active flow are
+     *   included.
+     * - The matched intent is included.
+     * - Other intents that could have matched end-user input, but did not match
+     *   because they are referenced by intent routes that are out of
+     *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+     *   are included.
+     * - Other intents referenced by intent routes in scope that matched end-user
+     *   input, but had a lower confidence score.
      * </pre>
      *
      * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -5338,8 +5446,20 @@ public Builder clearDiagnosticInfo() {
      *
      * <pre>
      * The free-form diagnostic info. For example, this field could contain
-     * webhook call latency. The string keys of the Struct's fields map can change
-     * without notice.
+     * webhook call latency. The fields of this data can change without notice,
+     * so you should not write code that depends on its structure.
+     * One of the fields is called "Alternative Matched Intents", which may
+     * aid with debugging. The following describes these intent results:
+     * - The list is empty if no intent was matched to end-user input.
+     * - Only intents that are referenced in the currently active flow are
+     *   included.
+     * - The matched intent is included.
+     * - Other intents that could have matched end-user input, but did not match
+     *   because they are referenced by intent routes that are out of
+     *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+     *   are included.
+     * - Other intents referenced by intent routes in scope that matched end-user
+     *   input, but had a lower confidence score.
      * </pre>
      *
      * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -5354,8 +5474,20 @@ public com.google.protobuf.Struct.Builder getDiagnosticInfoBuilder() {
      *
      * <pre>
      * The free-form diagnostic info. For example, this field could contain
-     * webhook call latency. The string keys of the Struct's fields map can change
-     * without notice.
+     * webhook call latency. The fields of this data can change without notice,
+     * so you should not write code that depends on its structure.
+     * One of the fields is called "Alternative Matched Intents", which may
+     * aid with debugging. The following describes these intent results:
+     * - The list is empty if no intent was matched to end-user input.
+     * - Only intents that are referenced in the currently active flow are
+     *   included.
+     * - The matched intent is included.
+     * - Other intents that could have matched end-user input, but did not match
+     *   because they are referenced by intent routes that are out of
+     *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+     *   are included.
+     * - Other intents referenced by intent routes in scope that matched end-user
+     *   input, but had a lower confidence score.
      * </pre>
      *
      * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -5374,8 +5506,20 @@ public com.google.protobuf.StructOrBuilder getDiagnosticInfoOrBuilder() {
      *
      * <pre>
      * The free-form diagnostic info. For example, this field could contain
-     * webhook call latency. The string keys of the Struct's fields map can change
-     * without notice.
+     * webhook call latency. The fields of this data can change without notice,
+     * so you should not write code that depends on its structure.
+     * One of the fields is called "Alternative Matched Intents", which may
+     * aid with debugging. The following describes these intent results:
+     * - The list is empty if no intent was matched to end-user input.
+     * - Only intents that are referenced in the currently active flow are
+     *   included.
+     * - The matched intent is included.
+     * - Other intents that could have matched end-user input, but did not match
+     *   because they are referenced by intent routes that are out of
+     *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+     *   are included.
+     * - Other intents referenced by intent routes in scope that matched end-user
+     *   input, but had a lower confidence score.
      * </pre>
      *
      * <code>.google.protobuf.Struct diagnostic_info = 10;</code>

java-dialogflow-cx/proto-google-cloud-dialogflow-cx-v3/src/main/java/com/google/cloud/dialogflow/cx/v3/QueryResultOrBuilder.java

@@ -652,8 +652,20 @@ com.google.cloud.dialogflow.cx.v3.ResponseMessageOrBuilder getResponseMessagesOr
    *
    * <pre>
    * The free-form diagnostic info. For example, this field could contain
-   * webhook call latency. The string keys of the Struct's fields map can change
-   * without notice.
+   * webhook call latency. The fields of this data can change without notice,
+   * so you should not write code that depends on its structure.
+   * One of the fields is called "Alternative Matched Intents", which may
+   * aid with debugging. The following describes these intent results:
+   * - The list is empty if no intent was matched to end-user input.
+   * - Only intents that are referenced in the currently active flow are
+   *   included.
+   * - The matched intent is included.
+   * - Other intents that could have matched end-user input, but did not match
+   *   because they are referenced by intent routes that are out of
+   *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+   *   are included.
+   * - Other intents referenced by intent routes in scope that matched end-user
+   *   input, but had a lower confidence score.
    * </pre>
    *
    * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -666,8 +678,20 @@ com.google.cloud.dialogflow.cx.v3.ResponseMessageOrBuilder getResponseMessagesOr
    *
    * <pre>
    * The free-form diagnostic info. For example, this field could contain
-   * webhook call latency. The string keys of the Struct's fields map can change
-   * without notice.
+   * webhook call latency. The fields of this data can change without notice,
+   * so you should not write code that depends on its structure.
+   * One of the fields is called "Alternative Matched Intents", which may
+   * aid with debugging. The following describes these intent results:
+   * - The list is empty if no intent was matched to end-user input.
+   * - Only intents that are referenced in the currently active flow are
+   *   included.
+   * - The matched intent is included.
+   * - Other intents that could have matched end-user input, but did not match
+   *   because they are referenced by intent routes that are out of
+   *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+   *   are included.
+   * - Other intents referenced by intent routes in scope that matched end-user
+   *   input, but had a lower confidence score.
    * </pre>
    *
    * <code>.google.protobuf.Struct diagnostic_info = 10;</code>
@@ -680,8 +704,20 @@ com.google.cloud.dialogflow.cx.v3.ResponseMessageOrBuilder getResponseMessagesOr
    *
    * <pre>
    * The free-form diagnostic info. For example, this field could contain
-   * webhook call latency. The string keys of the Struct's fields map can change
-   * without notice.
+   * webhook call latency. The fields of this data can change without notice,
+   * so you should not write code that depends on its structure.
+   * One of the fields is called "Alternative Matched Intents", which may
+   * aid with debugging. The following describes these intent results:
+   * - The list is empty if no intent was matched to end-user input.
+   * - Only intents that are referenced in the currently active flow are
+   *   included.
+   * - The matched intent is included.
+   * - Other intents that could have matched end-user input, but did not match
+   *   because they are referenced by intent routes that are out of
+   *   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+   *   are included.
+   * - Other intents referenced by intent routes in scope that matched end-user
+   *   input, but had a lower confidence score.
    * </pre>
    *
    * <code>.google.protobuf.Struct diagnostic_info = 10;</code>

java-dialogflow-cx/proto-google-cloud-dialogflow-cx-v3/src/main/proto/google/cloud/dialogflow/cx/v3/session.proto

@@ -617,8 +617,22 @@ message QueryResult {
   Match match = 15;
 
   // The free-form diagnostic info. For example, this field could contain
-  // webhook call latency. The string keys of the Struct's fields map can change
-  // without notice.
+  // webhook call latency. The fields of this data can change without notice,
+  // so you should not write code that depends on its structure.
+  //
+  // One of the fields is called "Alternative Matched Intents", which may
+  // aid with debugging. The following describes these intent results:
+  //
+  // - The list is empty if no intent was matched to end-user input.
+  // - Only intents that are referenced in the currently active flow are
+  //   included.
+  // - The matched intent is included.
+  // - Other intents that could have matched end-user input, but did not match
+  //   because they are referenced by intent routes that are out of
+  //   [scope](https://cloud.google.com/dialogflow/cx/docs/concept/handler#scope),
+  //   are included.
+  // - Other intents referenced by intent routes in scope that matched end-user
+  //   input, but had a lower confidence score.
   google.protobuf.Struct diagnostic_info = 10;
 
   // The sentiment analyss result, which depends on