Skip to content

Commit 6fe6205

Browse files
russcamrusscam
committed
Documentation improvements
1 parent f8eb790 commit 6fe6205

File tree

12 files changed

+42
-101
lines changed

12 files changed

+42
-101
lines changed

‎docs/asciidoc/client-concepts/low-level/post-data.asciidoc‎

Lines changed: 0 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -55,17 +55,7 @@ and passing a `PostData<object>` object to a method taking `PostData<object>` sh
5555
[source,csharp]
5656
----
5757
fromString = ImplicitlyConvertsFrom(fromString);
58-
----
5958
60-
[source,csharp]
61-
----
62-
await this.AssertOn(new ConnectionSettings());
63-
64-
await this.AssertOn(new ConnectionConfiguration());
65-
----
66-
67-
[source,csharp]
68-
----
6959
fromByteArray = ImplicitlyConvertsFrom(fromByteArray);
7060
fromListOfString = ImplicitlyConvertsFrom(fromListOfString);
7161
fromListOfObject = ImplicitlyConvertsFrom(fromListOfObject);
@@ -77,90 +67,3 @@ fromListOfObject.Type.Should().Be(PostType.EnumerableOfObject);
7767
fromObject.Type.Should().Be(PostType.Serializable);
7868
----
7969

80-
Although each implicitly types behaves slightly differently
81-
82-
[source,csharp]
83-
----
84-
await Post(() => @string, writes: Utf8Bytes(@string), storesBytes: true, settings: settings);
85-
86-
await Post(() => bytes, writes: bytes, storesBytes: true, settings: settings);
87-
----
88-
89-
When passing a list of strings we assume its a list of valid serialized json that we
90-
join with newline feeds making sure there is a trailing linefeed
91-
92-
[source,csharp]
93-
----
94-
await Post(() => listOfStrings, writes: multiStringJson, storesBytes: true, settings: settings);
95-
----
96-
97-
When passing a list of object we assume its a list of objects we need to serialize
98-
individually to json and join with newline feeds making sure there is a trailing linefeed
99-
100-
[source,csharp]
101-
----
102-
await Post(() => listOfObjects, writes: multiObjectJson, storesBytes: false, settings: settings);
103-
----
104-
105-
In all other cases postdata is serialized as is.
106-
107-
[source,csharp]
108-
----
109-
await Post(() => @object, writes: objectJson, storesBytes: false, settings: settings);
110-
----
111-
112-
If you want to maintain a copy of the request that went out, use `DisableDirectStreaming`
113-
114-
[source,csharp]
115-
----
116-
settings = new ConnectionSettings().DisableDirectStreaming();
117-
----
118-
119-
by forcing `DisableDirectStreaming` on connection settings, serialization happens first in a private `MemoryStream`
120-
so we can get hold of the serialized bytes
121-
122-
[source,csharp]
123-
----
124-
await Post(() => listOfObjects, writes: multiObjectJson, storesBytes: true, settings: settings);
125-
----
126-
127-
this behavior can also be observed when serializing a simple object using `DisableDirectStreaming`
128-
129-
[source,csharp]
130-
----
131-
await Post(() => @object, writes: objectJson, storesBytes: true, settings: settings);
132-
----
133-
134-
[source,csharp]
135-
----
136-
PostAssert(postData(), writes, storesBytes, settings);
137-
138-
await PostAssertAsync(postData(), writes, storesBytes, settings);
139-
----
140-
141-
[source,csharp]
142-
----
143-
postData.Write(ms, settings);
144-
145-
var sentBytes = ms.ToArray();
146-
147-
sentBytes.Should().Equal(writes);
148-
149-
postData.WrittenBytes.Should().NotBeNull();
150-
151-
postData.WrittenBytes.Should().BeNull();
152-
----
153-
154-
[source,csharp]
155-
----
156-
await postData.WriteAsync(ms, settings);
157-
158-
var sentBytes = ms.ToArray();
159-
160-
sentBytes.Should().Equal(writes);
161-
162-
postData.WrittenBytes.Should().NotBeNull();
163-
164-
postData.WrittenBytes.Should().BeNull();
165-
----
166-

‎docs/asciidoc/search/request/explain-usage.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99

1010
Enables explanation for each hit on how its score was computed.
1111

12+
See the Elasticsearch documentation on {ref_current}/search-explain.html[Explain] for more detail.
13+
1214
=== Fluent DSL Example
1315

1416
[source,csharp]

‎docs/asciidoc/search/request/fielddata-fields-usage.asciidoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@
77
[[fielddata-fields-usage]]
88
== Fielddata Fields Usage
99

10+
Allows to return the field data representation of a field for each hit.
11+
12+
See the Elasticsearch documentation on {ref_current}/search-request-fielddata-fields.html[Field Data Fields] for more detail.
13+
1014
=== Fluent DSL Example
1115

1216
[source,csharp]

‎docs/asciidoc/search/request/fields-usage.asciidoc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@
77
[[fields-usage]]
88
== Fields Usage
99

10+
Allows to selectively load specific stored fields for each document represented by a search hit.
11+
12+
WARNING: The `fields` parameter is about fields that are explicitly marked as stored in the mapping,
13+
which is off by default and generally not recommended.
14+
Use <<source-filtering-usage,source filtering>> instead to select subsets of the original source document to be returned.
15+
16+
See the Elasticsearch documentation on {ref_current}/search-request-fields.html[Fields] for more detail.
17+
1018
=== Fluent DSL Example
1119

1220
[source,csharp]

‎docs/asciidoc/search/request/query-usage.asciidoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
[[query-usage]]
88
== Query Usage
99

10-
The query element within the search request body allows to define a query using the Query DSL.
10+
The query element within the search request body allows to define a query using the <<query-dsl,Query DSL>>.
1111

1212
=== Fluent DSL Example
1313

‎docs/asciidoc/search/request/source-filtering-usage.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ Allows to control how the `_source` field is returned with every hit.
1111
By default operations return the contents of the `_source` field unless
1212
you have used the fields parameter or if the `_source` field is disabled.
1313

14+
See the Elasticsearch documentation on {ref_current}/search-request-source-filtering.html[Source Filtering] for more detail.
15+
1416
=== Fluent DSL Example
1517

1618
[source,csharp]

‎src/Tests/ClientConcepts/LowLevel/PostData.doc.cs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,12 +80,14 @@ [U] public void ImplicitConversions()
8080
fromObject.Type.Should().Be(PostType.Serializable);
8181
}
8282

83+
//hide
8384
[U] public async Task WritesCorrectlyUsingBothLowAndHighLevelSettings()
8485
{
8586
await this.AssertOn(new ConnectionSettings());
8687
await this.AssertOn(new ConnectionConfiguration());
8788
}
8889

90+
//hide
8991
private async Task AssertOn(IConnectionConfigurationValues settings)
9092
{
9193
/** Although each implicitly types behaves slightly differently */
@@ -117,12 +119,14 @@ private async Task AssertOn(IConnectionConfigurationValues settings)
117119
await Post(() => @object, writes: objectJson, storesBytes: true, settings: settings);
118120
}
119121

122+
//hide
120123
private static async Task Post(Func<PostData<object>> postData, byte[] writes, bool storesBytes, IConnectionConfigurationValues settings)
121124
{
122125
PostAssert(postData(), writes, storesBytes, settings);
123126
await PostAssertAsync(postData(), writes, storesBytes, settings);
124127
}
125128

129+
//hide
126130
private static void PostAssert(PostData<object> postData, byte[] writes, bool storesBytes, IConnectionConfigurationValues settings)
127131
{
128132
using (var ms = new MemoryStream())
@@ -137,6 +141,7 @@ private static void PostAssert(PostData<object> postData, byte[] writes, bool st
137141
}
138142
}
139143

144+
//hide
140145
private static async Task PostAssertAsync(PostData<object> postData, byte[] writes, bool storesBytes, IConnectionConfigurationValues settings)
141146
{
142147
using (var ms = new MemoryStream())
@@ -151,10 +156,13 @@ private static async Task PostAssertAsync(PostData<object> postData, byte[] writ
151156
}
152157
}
153158

159+
//hide
154160
private static byte[] Utf8Bytes(string s)
155161
{
156162
return string.IsNullOrEmpty(s) ? null : Encoding.UTF8.GetBytes(s);
157163
}
164+
165+
//hide
158166
private PostData<object> ImplicitlyConvertsFrom(PostData<object> postData) => postData;
159167

160168
}

‎src/Tests/Search/Request/ExplainUsageTests.cs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,9 @@ public class ExplainUsageTests : SearchUsageTestBase
1313
{
1414
/**
1515
* Enables explanation for each hit on how its score was computed.
16+
*
17+
* See the Elasticsearch documentation on {ref_current}/search-explain.html[Explain] for more detail.
1618
*/
17-
1819
public ExplainUsageTests(ReadOnlyCluster i, EndpointUsage usage) : base(i, usage) { }
1920

2021
protected override object ExpectJson =>

‎src/Tests/Search/Request/FielddataFieldsUsageTests.cs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@
55

66
namespace Tests.Search.Request
77
{
8+
/** Allows to return the field data representation of a field for each hit.
9+
*
10+
* See the Elasticsearch documentation on {ref_current}/search-request-fielddata-fields.html[Field Data Fields] for more detail.
11+
*/
812
public class FielddataFieldsUsageTests : SearchUsageTestBase
913
{
1014
public FielddataFieldsUsageTests(ReadOnlyCluster cluster, EndpointUsage usage) : base(cluster, usage) { }

‎src/Tests/Search/Request/FieldsUsageTests.cs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,14 @@
1010

1111
namespace Tests.Search.Request
1212
{
13+
/** Allows to selectively load specific stored fields for each document represented by a search hit.
14+
*
15+
* WARNING: The `fields` parameter is about fields that are explicitly marked as stored in the mapping,
16+
* which is off by default and generally not recommended.
17+
* Use <<source-filtering-usage,source filtering>> instead to select subsets of the original source document to be returned.
18+
*
19+
* See the Elasticsearch documentation on {ref_current}/search-request-fields.html[Fields] for more detail.
20+
*/
1321
public class FieldsUsageTests : SearchUsageTestBase
1422
{
1523
public FieldsUsageTests(ReadOnlyCluster cluster, EndpointUsage usage) : base(cluster, usage) { }

0 commit comments

Comments
 (0)