From 0b6d9f90cf8a5f5debac5a3f61606b5ab5e3d3d5 Mon Sep 17 00:00:00 2001
From: Pascal Seitz <pascal.seitz@gmail.com>
Date: Wed, 16 Mar 2022 12:39:26 +0800
Subject: [PATCH] improve docs

---
 src/aggregation/agg_result.rs                 | 10 +++++-----
 src/aggregation/bucket/histogram/histogram.rs | 16 ++++++++++++----
 src/aggregation/bucket/range.rs               | 11 ++++++++---
 3 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/src/aggregation/agg_result.rs b/src/aggregation/agg_result.rs
index d83673c5e..5049b125d 100644
--- a/src/aggregation/agg_result.rs
+++ b/src/aggregation/agg_result.rs
@@ -90,7 +90,7 @@ pub enum BucketResult {
         ///
         /// If there are holes depends on the request, if min_doc_count is 0, then there are no
         /// holes between the first and last bucket.
-        /// See [HistogramAggregation](super::agg_request::HistogramAggregation)
+        /// See [HistogramAggregation](super::bucket::HistogramAggregation)
         buckets: Vec<BucketEntry>,
     },
 }
@@ -161,7 +161,7 @@ impl From<IntermediateBucketResult> for BucketResult {
 /// sub_aggregations.
 ///
 /// # JSON Format
-/// ```ignore
+/// ```json
 /// {
 ///   ...
 ///     "my_histogram": {
@@ -182,7 +182,7 @@ impl From<IntermediateBucketResult> for BucketResult {
 ///    }
 ///    ...
 /// }
-///  ```
+/// ```
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct BucketEntry {
     /// The identifier of the bucket.
@@ -208,7 +208,7 @@ impl From<IntermediateHistogramBucketEntry> for BucketEntry {
 /// sub_aggregations.
 ///
 /// # JSON Format
-/// ```ignore
+/// ```json
 /// {
 ///   ...
 ///     "my_ranges": {
@@ -233,7 +233,7 @@ impl From<IntermediateHistogramBucketEntry> for BucketEntry {
 ///    }
 ///    ...
 /// }
-///  ```
+/// ```
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct RangeBucketEntry {
     /// The identifier of the bucket.
diff --git a/src/aggregation/bucket/histogram/histogram.rs b/src/aggregation/bucket/histogram/histogram.rs
index 9d8bb51cd..99b9f1a93 100644
--- a/src/aggregation/bucket/histogram/histogram.rs
+++ b/src/aggregation/bucket/histogram/histogram.rs
@@ -34,7 +34,7 @@ use crate::{DocId, TantivyError};
 ///
 /// # Result
 /// Result type is [BucketResult](crate::aggregation::agg_result::BucketResult) with
-/// [RangeBucketEntry](crate::aggregation::agg_result::BucketEntry) on the
+/// [BucketEntry](crate::aggregation::agg_result::BucketEntry) on the
 /// AggregationCollector.
 ///
 /// Result type is
@@ -42,8 +42,12 @@ use crate::{DocId, TantivyError};
 /// [crate::aggregation::intermediate_agg_result::IntermediateHistogramBucketEntry] on the
 /// DistributedAggregationCollector.
 ///
-/// # Request JSON Format
-/// ```ignore
+/// # Limitations/Compatibility
+///
+/// The keyed parameter (elasticsearch) is not yet supported.
+///
+/// # JSON Format
+/// ```json
 /// {
 ///     "prices": {
 ///         "histogram": {
@@ -52,7 +56,11 @@ use crate::{DocId, TantivyError};
 ///         }
 ///     }
 /// }
-///  ```
+/// ```
+///
+/// Response
+/// See [BucketEntry](crate::aggregation::agg_result::BucketEntry)
+
 #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
 pub struct HistogramAggregation {
     /// The field to aggregate on.
diff --git a/src/aggregation/bucket/range.rs b/src/aggregation/bucket/range.rs
index 39631ffee..2715993b3 100644
--- a/src/aggregation/bucket/range.rs
+++ b/src/aggregation/bucket/range.rs
@@ -30,8 +30,13 @@ use crate::{DocId, TantivyError};
 /// [crate::aggregation::intermediate_agg_result::IntermediateRangeBucketEntry] on the
 /// DistributedAggregationCollector.
 ///
+/// # Limitations/Compatibility
+/// Overlapping ranges are not yet supported.
+///
+/// The keyed parameter (elasticsearch) is not yet supported.
+///
 /// # Request JSON Format
-/// ```ignore
+/// ```json
 /// {
 ///     "range": {
 ///         "field": "score",
@@ -42,8 +47,8 @@ use crate::{DocId, TantivyError};
 ///             { "from": 20.0 }
 ///         ]
 ///     }
-///  }
-///  ```
+/// }
+/// ```
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct RangeAggregation {
     /// The field to aggregate on.