Add search usage to docs

Visit foreach statements when generating source code documentation
Add ability to hide code with preceding //hide comment
Tidy up existing docs

Author: russcam

docs/asciidoc/aggregations/bucket/date-histogram/date-histogram-aggregation-usage.asciidoc

@@ -129,11 +129,17 @@ var dateHistogram = response.Aggs.DateHistogram("projects_started_per_month");
 dateHistogram.Should().NotBeNull();
 dateHistogram.Buckets.Should().NotBeNull();
 dateHistogram.Buckets.Count.Should().BeGreaterThan(10);
-item.Date.Should().NotBe(default(DateTime));
-item.DocCount.Should().BeGreaterThan(0);
-var nested = item.Nested("project_tags");
-nested.Should().NotBeNull();
-var nestedTerms = nested.Terms("tags");
-nestedTerms.Buckets.Count.Should().BeGreaterThan(0);
+
+foreach (var item in dateHistogram.Buckets)
+{
+    item.Date.Should().NotBe(default(DateTime));
+    item.DocCount.Should().BeGreaterThan(0);
+
+    var nested = item.Nested("project_tags");
+    nested.Should().NotBeNull();
+
+    var nestedTerms = nested.Terms("tags");
+    nestedTerms.Buckets.Count.Should().BeGreaterThan(0);
+}
 ----
 

docs/asciidoc/aggregations/bucket/date-range/date-range-aggregation-usage.asciidoc

@@ -105,12 +105,13 @@ dateHistogram.Buckets.Should().NotBeNull();
 
 We specified three ranges so we expect to have three of them in the response 
 
-=== Handling Responses
-
 [source,csharp]
 ----
 dateHistogram.Buckets.Count.Should().Be(3);
 
-item.DocCount.Should().BeGreaterThan(0);
+foreach (var item in dateHistogram.Buckets)
+{
+    item.DocCount.Should().BeGreaterThan(0);
+}
 ----
 

docs/asciidoc/aggregations/bucket/filters/filters-aggregation-usage.asciidoc

@@ -235,7 +235,12 @@ var filterAgg = response.Aggs.Filters("projects_by_state");
 filterAgg.Should().NotBeNull();
 var results = filterAgg.AnonymousBuckets();
 results.Count.Should().Be(4);
-singleBucket.DocCount.Should().BeGreaterThan(0);
+
+foreach (var singleBucket in results.Take(3))
+{
+    singleBucket.DocCount.Should().BeGreaterThan(0);
+}
+
 results.Last().DocCount.Should().Be(0); <1>
 ----
 <1> The last bucket is the _other bucket_

docs/asciidoc/aggregations/bucket/histogram/histogram-aggregation-usage.asciidoc

@@ -64,6 +64,8 @@ new SearchRequest<Project>
 response.IsValid.Should().BeTrue();
 var commits = response.Aggs.Histogram("commits");
 commits.Should().NotBeNull();
-item.DocCount.Should().BeGreaterThan(0);
+
+foreach (var item in commits.Buckets)
+    item.DocCount.Should().BeGreaterThan(0);
 ----
 

docs/asciidoc/aggregations/bucket/ip-range/ip-range-aggregation-usage.asciidoc

@@ -72,6 +72,8 @@ var ipRanges = response.Aggs.IpRange("ip_ranges");
 ipRanges.Should().NotBeNull();
 ipRanges.Buckets.Should().NotBeNull();
 ipRanges.Buckets.Count.Should().BeGreaterThan(0);
-range.DocCount.Should().BeGreaterThan(0);
+
+foreach (var range in ipRanges.Buckets)
+    range.DocCount.Should().BeGreaterThan(0);
 ----
 

docs/asciidoc/aggregations/bucket/nested/nested-aggregation-usage.asciidoc

@@ -71,7 +71,11 @@ var tags = response.Aggs.Nested("tags");
 tags.Should().NotBeNull();
 var tagNames = tags.Terms("tag_names");
 tagNames.Should().NotBeNull();
-item.Key.Should().NotBeNullOrEmpty();
-item.DocCount.Should().BeGreaterThan(0);
+
+foreach(var item in tagNames.Buckets)
+{
+    item.Key.Should().NotBeNullOrEmpty();
+    item.DocCount.Should().BeGreaterThan(0);
+}
 ----
 

docs/asciidoc/aggregations/bucket/reverse-nested/reverse-nested-aggregation-usage.asciidoc

@@ -99,13 +99,20 @@ var tags = response.Aggs.Nested("tags");
 tags.Should().NotBeNull();
 var tagNames = tags.Terms("tag_names");
 tagNames.Should().NotBeNull();
-tagName.Key.Should().NotBeNullOrEmpty();
-tagName.DocCount.Should().BeGreaterThan(0);
-var tagsToProjects = tagName.ReverseNested("tags_to_project");
-tagsToProjects.Should().NotBeNull();
-var topProjectsPerTag = tagsToProjects.Terms("top_projects_per_tag");
-topProjectsPerTag.Should().NotBeNull();
-topProject.Key.Should().NotBeNullOrEmpty();
-topProject.DocCount.Should().BeGreaterThan(0);
+
+foreach(var tagName in tagNames.Buckets)
+{
+    tagName.Key.Should().NotBeNullOrEmpty();
+    tagName.DocCount.Should().BeGreaterThan(0);
+    var tagsToProjects = tagName.ReverseNested("tags_to_project");
+    tagsToProjects.Should().NotBeNull();
+    var topProjectsPerTag = tagsToProjects.Terms("top_projects_per_tag");
+    topProjectsPerTag.Should().NotBeNull();
+    foreach(var topProject in topProjectsPerTag.Buckets)
+    {
+        topProject.Key.Should().NotBeNullOrEmpty();
+        topProject.DocCount.Should().BeGreaterThan(0);
+    }
+}
 ----
 

docs/asciidoc/aggregations/bucket/terms/terms-aggregation-usage.asciidoc

@@ -103,8 +103,13 @@ var states = response.Aggs.Terms("states");
 states.Should().NotBeNull();
 states.DocCountErrorUpperBound.Should().HaveValue();
 states.SumOtherDocCount.Should().HaveValue();
-item.Key.Should().NotBeNullOrEmpty();
-item.DocCount.Should().BeGreaterOrEqualTo(1);
+
+foreach (var item in states.Buckets)
+{
+    item.Key.Should().NotBeNullOrEmpty();
+    item.DocCount.Should().BeGreaterOrEqualTo(1);
+}
+
 states.Meta.Should().NotBeNull().And.HaveCount(1);
 states.Meta["foo"].Should().Be("bar");
 ----

docs/asciidoc/aggregations/metric/percentile-ranks/percentile-ranks-aggregation-usage.asciidoc

@@ -79,6 +79,8 @@ response.IsValid.Should().BeTrue();
 var commitsOutlier = response.Aggs.PercentileRanks("commits_outlier");
 commitsOutlier.Should().NotBeNull();
 commitsOutlier.Items.Should().NotBeNullOrEmpty();
-item.Should().NotBeNull();
+
+foreach (var item in commitsOutlier.Items)
+    item.Should().NotBeNull();
 ----
 

docs/asciidoc/aggregations/metric/percentiles/percentiles-aggregation-usage.asciidoc

@@ -80,6 +80,8 @@ response.IsValid.Should().BeTrue();
 var commitsOutlier = response.Aggs.Percentiles("commits_outlier");
 commitsOutlier.Should().NotBeNull();
 commitsOutlier.Items.Should().NotBeNullOrEmpty();
-item.Value.Should().BeGreaterThan(0);
+
+foreach (var item in commitsOutlier.Items)
+    item.Value.Should().BeGreaterThan(0);
 ----