add comments

Author: empiredan

src/shell/commands/node_management.cpp

@@ -307,6 +307,10 @@ struct replica_server_stats
 {
     replica_server_stats() = default;
 
+    // `DEFINE_JSON_SERIALIZATION` is not used to encode the member variables of
+    // `replica_server_stats` into JSON because the number of its member variables
+    // is very large and far exceeds the parameter limit of this macro. Increasing
+    // the macro's parameter limit would make the code overly verbose.
     std::string to_json_string() const
     {
         nlohmann::json rpc;

src/utils/metrics.cpp

@@ -390,6 +390,11 @@ void metrics_http_service::get_metrics_handler(const http_request &req, http_res
         filters.with_metric_fields = kBriefMetricFields;
     }
 
+    // If the client specifies `as_value=true` in the HTTP request, it is necessary to
+    // check whether metrics in `with_metric_fields` that contain multiple values (such
+    // as percentiles) only need to return a single value to the client. If so, the
+    // server-side `as_value` should be set to true, so that the returned field name
+    // in the response is "value".
     if (as_value) {
         int kth_count{0};
         for (const auto &kth : kAllKthPercentiles) {

src/utils/metrics.h

@@ -537,6 +537,17 @@ struct metric_filters
 
     entity_metrics_type entity_metrics;
 
+    // When the `as_value` field is used to construct the query string in an HTTP request,
+    // setting it to true means that for metrics with multiple values (such as percentiles),
+    // if the server determines that only a single value will be returned to the client, it
+    // should name that field "value" instead of something like "p99".
+    //
+    // When the `as_value` field is used on the HTTP server side to process a request, true
+    // means that for multi-value metrics (such as percentiles), only one value will be
+    // returned to the client, and this single returned field will be named "value".
+    //
+    // This parameter can greatly simplify the structured processing of JSON responses
+    // returned by the server.
     bool as_value{false};
 };
 
@@ -1401,6 +1412,10 @@ class percentile : public closeable_metric
                 continue;
             }
 
+            // If `as_value` is true, then for metrics with multiple values (such as
+            // percentiles), only one value needs to be returned to the client. Therefore,
+            // its field name is set to "value" and the loop is exited (since only a single
+            // value is required to be returned).
             if (filters.as_value) {
                 encode(writer, kMetricSingleValueField, value(i));
                 break;