[7.x] [DOCS] Reformat avg bucket agg reference (#69751)

docs/Versions.asciidoc

@@ -15,7 +15,8 @@ include::{docs-root}/shared/versions/stack/{source_branch}.asciidoc[]
 ///////
 Javadoc roots used to generate links from Painless's API reference
 ///////
-:java11-javadoc: https://docs.oracle.com/en/java/javase/11/docs/api
+:javadoc:             https://docs.oracle.com/en/java/javase/{jdk_major}/docs/api
+:java11-javadoc:      https://docs.oracle.com/en/java/javase/11/docs/api
 :lucene-core-javadoc: https://lucene.apache.org/core/{lucene_version_path}/core
 
 ifeval::["{release-state}"=="unreleased"]

docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc

@@ -1,44 +1,61 @@
 [[search-aggregations-pipeline-avg-bucket-aggregation]]
-=== Avg bucket aggregation
+=== Average bucket aggregation
 ++++
-<titleabbrev>Avg bucket</titleabbrev>
+<titleabbrev>Average bucket</titleabbrev>
 ++++
 
-A sibling pipeline aggregation which calculates the (mean) average value of a specified metric in a sibling aggregation.
-The specified metric must be numeric and the sibling aggregation must be a multi-bucket aggregation.
+A sibling pipeline aggregation which calculates the mean value of a specified
+metric in a sibling aggregation. The specified metric must be numeric and the
+sibling aggregation must be a multi-bucket aggregation.
 
 [[avg-bucket-agg-syntax]]
 ==== Syntax
 
-An `avg_bucket` aggregation looks like this in isolation:
-
-[source,js]
---------------------------------------------------
-{
-  "avg_bucket": {
-    "buckets_path": "the_sum"
-  }
-}
---------------------------------------------------
+[source,js,indent=0]
+----
+include::avg-bucket-aggregation.asciidoc[tag=avg-bucket-agg-syntax]
+----
 // NOTCONSOLE
 
 [[avg-bucket-params]]
-.`avg_bucket` Parameters
-[options="header"]
-|===
-|Parameter Name |Description |Required |Default Value
-|`buckets_path` |The path to the buckets we wish to find the average for (see <<buckets-path-syntax>> for more
- details) |Required |
- |`gap_policy` |The policy to apply when gaps are found in the data (see <<gap-policy>> for more
- details) |Optional |`skip`
- |`format` |format to apply to the output value of this aggregation |Optional | `null`
-|===
-
-The following snippet calculates the average of the total monthly `sales`:
-
-[source,console]
---------------------------------------------------
-POST /_search
+==== Parameters
+
+`buckets_path`::
+(Required, string)
+Path to the buckets to average. For syntax, see <<buckets-path-syntax>>.
+
+`gap_policy`::
+(Optional, string)
+Policy to apply when gaps are found in the data. For valid values, see
+<<buckets-path-syntax>>. Defaults to `skip`.
+
+`format`::
+(Optional, string)
+{javadoc}/java.base/java/text/DecimalFormat.html[DecimalFormat pattern] for the
+output value. If specified, the formatted value is returned in the aggregation's
+`value_as_string` property.
+
+[[avg-bucket-agg-response]]
+==== Response body
+
+`value`::
+(float)
+Mean average value for the metric specified in `buckets_path`.
+
+`value_as_string`::
+(string)
+Formatted output value for the aggregation. This property is only provided if
+a `format` is specified in the request.
+
+[[avg-bucket-agg-ex]]
+==== Example
+
+The following `avg_monthly_sales` aggregation uses `avg_bucket` to calculate
+average sales per month:
+
+[source,console,subs="specialchars+"]
+----
+POST _search
 {
   "size": 0,
   "aggs": {
@@ -56,63 +73,67 @@ POST /_search
       }
     },
     "avg_monthly_sales": {
+// tag::avg-bucket-agg-syntax[]               <1>
       "avg_bucket": {
-        "buckets_path": "sales_per_month>sales" <1>
+        "buckets_path": "sales_per_month>sales",
+        "gap_policy": "skip",
+        "format": "#,##0.00;(#,##0.00)"
       }
+// end::avg-bucket-agg-syntax[]               <2>
     }
   }
 }
-
---------------------------------------------------
+----
 // TEST[setup:sales]
 
-<1> `buckets_path` instructs this avg_bucket aggregation that we want the (mean) average value of the `sales` aggregation in the
-`sales_per_month` date histogram.
+<1> Start of the `avg_bucket` configuration. Comment is not part of the example.
+<2> End of the `avg_bucket` configuration. Comment is not part of the example.
 
-And the following may be the response:
+The request returns the following response:
 
 [source,console-result]
---------------------------------------------------
+----
 {
-   "took": 11,
-   "timed_out": false,
-   "_shards": ...,
-   "hits": ...,
-   "aggregations": {
-      "sales_per_month": {
-         "buckets": [
-            {
-               "key_as_string": "2015/01/01 00:00:00",
-               "key": 1420070400000,
-               "doc_count": 3,
-               "sales": {
-                  "value": 550.0
-               }
-            },
-            {
-               "key_as_string": "2015/02/01 00:00:00",
-               "key": 1422748800000,
-               "doc_count": 2,
-               "sales": {
-                  "value": 60.0
-               }
-            },
-            {
-               "key_as_string": "2015/03/01 00:00:00",
-               "key": 1425168000000,
-               "doc_count": 2,
-               "sales": {
-                  "value": 375.0
-               }
-            }
-         ]
-      },
-      "avg_monthly_sales": {
-          "value": 328.33333333333333
-      }
-   }
+  "took": 11,
+  "timed_out": false,
+  "_shards": ...,
+  "hits": ...,
+  "aggregations": {
+    "sales_per_month": {
+      "buckets": [
+        {
+          "key_as_string": "2015/01/01 00:00:00",
+          "key": 1420070400000,
+          "doc_count": 3,
+          "sales": {
+            "value": 550.0
+          }
+        },
+        {
+          "key_as_string": "2015/02/01 00:00:00",
+          "key": 1422748800000,
+          "doc_count": 2,
+          "sales": {
+            "value": 60.0
+          }
+        },
+        {
+          "key_as_string": "2015/03/01 00:00:00",
+          "key": 1425168000000,
+          "doc_count": 2,
+          "sales": {
+            "value": 375.0
+          }
+        }
+      ]
+    },
+    "avg_monthly_sales": {
+      "value": 328.33333333333333,
+      "value_as_string": "328.33"
+    }
+  }
 }
---------------------------------------------------
+----
 // TESTRESPONSE[s/"took": 11/"took": $body.took/]
 // TESTRESPONSE[s/"_shards": \.\.\./"_shards": $body._shards/]
 // TESTRESPONSE[s/"hits": \.\.\./"hits": $body.hits/]