admin-docs: add some clarifications and use proper note annotations in admin-clusters docs (#39087)

Signed-off-by: Rohit Agrawal <rohit.agrawal@databricks.com>

Mirrored from https://github.com/envoyproxy/envoy @ ea68d89822e40c3279392147e578348b2e88db28

Author: update-envoy[bot]

envoy/admin/v3/clusters.proto

@@ -41,22 +41,24 @@ message ClusterStatus {
   bool added_via_api = 2;
 
   // The success rate threshold used in the last interval.
-  // If
-  // :ref:`outlier_detection.split_external_local_origin_errors<envoy_v3_api_field_config.cluster.v3.OutlierDetection.split_external_local_origin_errors>`
-  // is ``false``, all errors: externally and locally generated were used to calculate the threshold.
-  // If
-  // :ref:`outlier_detection.split_external_local_origin_errors<envoy_v3_api_field_config.cluster.v3.OutlierDetection.split_external_local_origin_errors>`
-  // is ``true``, only externally generated errors were used to calculate the threshold.
-  // The threshold is used to eject hosts based on their success rate. See
-  // :ref:`Cluster outlier detection <arch_overview_outlier_detection>` documentation for details.
   //
-  // Note: this field may be omitted in any of the three following cases:
+  // * If :ref:`outlier_detection.split_external_local_origin_errors<envoy_v3_api_field_config.cluster.v3.OutlierDetection.split_external_local_origin_errors>`
+  //   is ``false``, all errors: externally and locally generated were used to calculate the threshold.
+  // * If :ref:`outlier_detection.split_external_local_origin_errors<envoy_v3_api_field_config.cluster.v3.OutlierDetection.split_external_local_origin_errors>`
+  //   is ``true``, only externally generated errors were used to calculate the threshold.
+  //
+  // The threshold is used to eject hosts based on their success rate. For more information, see the
+  // :ref:`Cluster outlier detection <arch_overview_outlier_detection>` documentation.
+  //
+  // .. note::
+  //
+  //   This field may be omitted in any of the three following cases:
+  //
+  //   1. There were not enough hosts with enough request volume to proceed with success rate based outlier ejection.
+  //   2. The threshold is computed to be < 0 because a negative value implies that there was no threshold for that
+  //      interval.
+  //   3. Outlier detection is not enabled for this cluster.
   //
-  // 1. There were not enough hosts with enough request volume to proceed with success rate based
-  //    outlier ejection.
-  // 2. The threshold is computed to be < 0 because a negative value implies that there was no
-  //    threshold for that interval.
-  // 3. Outlier detection is not enabled for this cluster.
   type.v3.Percent success_rate_ejection_threshold = 3;
 
   // Mapping from host address to the host's current status.
@@ -67,16 +69,18 @@ message ClusterStatus {
   // This field should be interpreted only when
   // :ref:`outlier_detection.split_external_local_origin_errors<envoy_v3_api_field_config.cluster.v3.OutlierDetection.split_external_local_origin_errors>`
   // is ``true``. The threshold is used to eject hosts based on their success rate.
-  // See :ref:`Cluster outlier detection <arch_overview_outlier_detection>` documentation for
-  // details.
   //
-  // Note: this field may be omitted in any of the three following cases:
+  // For more information, see the :ref:`Cluster outlier detection <arch_overview_outlier_detection>` documentation.
+  //
+  // .. note::
+  //
+  //   This field may be omitted in any of the three following cases:
+  //
+  //   1. There were not enough hosts with enough request volume to proceed with success rate based outlier ejection.
+  //   2. The threshold is computed to be < 0 because a negative value implies that there was no threshold for that
+  //      interval.
+  //   3. Outlier detection is not enabled for this cluster.
   //
-  // 1. There were not enough hosts with enough request volume to proceed with success rate based
-  //    outlier ejection.
-  // 2. The threshold is computed to be < 0 because a negative value implies that there was no
-  //    threshold for that interval.
-  // 3. Outlier detection is not enabled for this cluster.
   type.v3.Percent local_origin_success_rate_ejection_threshold = 5;
 
   // :ref:`Circuit breaking <arch_overview_circuit_break>` settings of the cluster.
@@ -103,19 +107,20 @@ message HostStatus {
   // The host's current health status.
   HostHealthStatus health_status = 3;
 
-  // Request success rate for this host over the last calculated interval.
-  // If
-  // :ref:`outlier_detection.split_external_local_origin_errors<envoy_v3_api_field_config.cluster.v3.OutlierDetection.split_external_local_origin_errors>`
-  // is ``false``, all errors: externally and locally generated were used in success rate
-  // calculation. If
-  // :ref:`outlier_detection.split_external_local_origin_errors<envoy_v3_api_field_config.cluster.v3.OutlierDetection.split_external_local_origin_errors>`
-  // is ``true``, only externally generated errors were used in success rate calculation.
-  // See :ref:`Cluster outlier detection <arch_overview_outlier_detection>` documentation for
-  // details.
+  // The success rate for this host during the last measurement interval.
+  //
+  // * If :ref:`outlier_detection.split_external_local_origin_errors<envoy_v3_api_field_config.cluster.v3.OutlierDetection.split_external_local_origin_errors>`
+  //   is ``false``, all errors: externally and locally generated were used in success rate calculation.
+  // * If :ref:`outlier_detection.split_external_local_origin_errors<envoy_v3_api_field_config.cluster.v3.OutlierDetection.split_external_local_origin_errors>`
+  //   is ``true``, only externally generated errors were used in success rate calculation.
+  //
+  // For more information, see the :ref:`Cluster outlier detection <arch_overview_outlier_detection>` documentation.
+  //
+  // .. note::
+  //
+  //   The message will be missing if the host didn't receive enough traffic to calculate a reliable success rate, or
+  //   if the cluster had too few hosts to apply outlier ejection based on success rate.
   //
-  // Note: the message will not be present if host did not have enough request volume to calculate
-  // success rate or the cluster did not have enough hosts to run through success rate outlier
-  // ejection.
   type.v3.Percent success_rate = 4;
 
   // The host's weight. If not configured, the value defaults to 1.
@@ -127,18 +132,20 @@ message HostStatus {
   // The host's priority. If not configured, the value defaults to 0 (highest priority).
   uint32 priority = 7;
 
-  // Request success rate for this host over the last calculated
-  // interval when only locally originated errors are taken into account and externally originated
-  // errors were treated as success.
-  // This field should be interpreted only when
+  // The success rate for this host during the last interval, considering only locally generated errors. Externally
+  // generated errors are treated as successes.
+  //
+  // This field is only relevant when
   // :ref:`outlier_detection.split_external_local_origin_errors<envoy_v3_api_field_config.cluster.v3.OutlierDetection.split_external_local_origin_errors>`
-  // is ``true``.
-  // See :ref:`Cluster outlier detection <arch_overview_outlier_detection>` documentation for
-  // details.
+  // is set to ``true``.
+  //
+  // For more information, see the :ref:`Cluster outlier detection <arch_overview_outlier_detection>` documentation.
+  //
+  // .. note::
+  //
+  //   The message will be missing if the host didn’t receive enough traffic to compute a success rate, or if the
+  //   cluster didn’t have enough hosts to perform outlier ejection based on success rate.
   //
-  // Note: the message will not be present if host did not have enough request volume to calculate
-  // success rate or the cluster did not have enough hosts to run through success rate outlier
-  // ejection.
   type.v3.Percent local_origin_success_rate = 8;
 
   // locality of the host.