Documentation for Union type (#3059)

Author: russcam

docs/common-options/union/union.asciidoc

@@ -0,0 +1,95 @@
+:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/6.1
+
+:github: https://github.com/elastic/elasticsearch-net
+
+:nuget: https://www.nuget.org/packages
+
+////
+IMPORTANT NOTE
+==============
+This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/CommonOptions/Union/Union.doc.cs. 
+If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
+please modify the original csharp file found at the link and submit the PR with that change. Thanks!
+////
+
+[[union]]
+=== Union type
+
+Some API parameters within Elasticsearch can accept more than one JSON data structure, for example, source filtering on
+a search request can accept
+
+* a `bool` value to disable `_source` retrieval
+
+* a `string` value representing a wildcard pattern to control what parts of `_source` to return
+
+* an array of `string` values representing multiple wildcard patterns to control what parts of `_source` to return
+
+* an `object` with `includes` and `excludes` properties that each accept an array of wildcard patterns to control
+what parts of `_source` to include and exclude, respectively.
+
+That's a lot of different flexibility! NEST includes a `Union<TFirst,TSecond>` type to make it easier to work with
+these kinds of parameters, forming the union of two types, `TFirst` and `TSecond`.
+
+==== Implicit conversion
+
+The `Union<TFirst,TSecond>` has implicit operators to convert from an instance of `TFirst` or `TSecond` to an
+instance of `Union<TFirst,TSecond>`. This is often the easiest way of construction an instance
+
+[source,csharp]
+----
+Union<bool, ISourceFilter> sourceFilterFalse = false;
+
+Union<bool, ISourceFilter> sourceFilterInterface = new SourceFilter
+{
+    Includes = new [] { "foo.*" }
+};
+----
+
+==== Constructor
+
+Sometimes, the constructor of `Union<TFirst,TSecond>` may be required in cases where the compiler is
+unable to infer the correct implicit conversion
+
+[source,csharp]
+----
+var sourceFilterTrue = new Union<bool, ISourceFilter>(true);
+
+var sourceFilterInterface = new Union<bool, ISourceFilter>(new SourceFilter
+{
+    Includes = new [] { "foo.*" }
+});
+----
+
+==== Match
+
+The `Match` method can be used to operate on the value encapsulated by the instance of `Union<TFirst,TSecond>`.
+Two delegates are passed; one to operate on a `TFirst` value and the other toe operate on a `TSecond` value.
+
+[source,csharp]
+----
+sourceFilterTrue.Match(
+    b => b.Should().BeTrue(),
+    s => s.Should().BeNull());
+
+sourceFilterInterface.Match(
+    b => b.Should().BeFalse(),
+    s => s.Should().NotBeNull());
+----
+
+The delegates can also return a value
+
+[source,csharp]
+----
+var serializedFilterTrue = sourceFilterTrue.Match(
+    b => serializer.SerializeToString(b),
+    s => null);
+
+serializedFilterTrue.Should().Be("true");
+
+var serializedFilterInterface = sourceFilterTrue.Match(
+    b => null,
+    s => serializer.SerializeToString(s));
+
+serializedFilterInterface.Should().Be("{\"includes\":[\"foo.*\"]}");
+----
+

docs/high-level.asciidoc

@@ -49,6 +49,8 @@ As well as a number of types for working with
 
 * <<date-math-expressions, Date Math>>
 
+* <<union, Union types>>
+
 And features such as
 
 * <<mapping, Mapping CLR POCO types to JSON documents>>
@@ -258,9 +260,13 @@ NEST has a number of types for working with Elasticsearch conventions for
 
 * <<date-math-expressions, Date Math expressions>>
 
+* <<union, Union types>>
+
 include::common-options/time-unit/time-units.asciidoc[]
 
 include::common-options/distance-unit/distance-units.asciidoc[]
 
 include::common-options/date-math/date-math-expressions.asciidoc[]
 
+include::common-options/union/union.asciidoc[]
+

src/Nest/Aggregations/Bucket/Terms/TermsExclude.cs

@@ -3,23 +3,36 @@
 
 namespace Nest
 {
+	/// <summary>
+	/// Filters which terms to exclude from the response
+	/// </summary>
 	[JsonConverter(typeof(TermsExcludeJsonConverter))]
 	public class TermsExclude
 	{
+		/// <summary>
+		/// The regular expression pattern to determine terms to exclude from the response
+		/// </summary>
 		[JsonIgnore]
 		public string Pattern { get; set; }
 
+		/// <summary>
+		/// Collection of terms to exclude from the response
+		/// </summary>
 		[JsonIgnore]
 		public IEnumerable<string> Values { get; set; }
 
-		public TermsExclude(string pattern)
-		{
-			Pattern = pattern;
-		}
+		/// <summary>
+		/// Creates an instance of <see cref="TermsExclude"/> that uses a regular expression pattern
+		/// to determine the terms to exclude from the response
+		/// </summary>
+		/// <param name="pattern">The regular expression pattern</param>
+		public TermsExclude(string pattern) => Pattern = pattern;
 
-		public TermsExclude(IEnumerable<string> values)
-		{
-			Values = values;
-		}
+		/// <summary>
+		/// Creates an instance of <see cref="TermsExclude"/> that uses a collection of terms
+		/// to exclude from the response
+		/// </summary>
+		/// <param name="values">The exact terms to exclude</param>
+		public TermsExclude(IEnumerable<string> values) => Values = values;
 	}
-}
+}

src/Nest/Aggregations/Bucket/Terms/TermsInclude.cs

@@ -4,12 +4,21 @@
 
 namespace Nest
 {
+	/// <summary>
+	/// Filters which terms to include in the response
+	/// </summary>
 	[JsonConverter(typeof(TermsIncludeJsonConverter))]
 	public class TermsInclude
 	{
+		/// <summary>
+		/// The regular expression pattern to determine terms to include in the response
+		/// </summary>
 		[JsonIgnore]
 		public string Pattern { get; set; }
 
+		/// <summary>
+		/// Collection of terms to include in the response
+		/// </summary>
 		[JsonIgnore]
 		public IEnumerable<string> Values { get; set; }
 
@@ -25,16 +34,26 @@ public class TermsInclude
 		[JsonProperty("num_partitions")]
 		public long? NumberOfPartitions { get; set; }
 
-		public TermsInclude(string pattern)
-		{
-			Pattern = pattern;
-		}
+		/// <summary>
+		/// Creates an instance of <see cref="TermsInclude"/> that uses a regular expression pattern
+		/// to determine the terms to include in the response
+		/// </summary>
+		/// <param name="pattern">The regular expression pattern</param>
+		public TermsInclude(string pattern) => Pattern = pattern;
 
-		public TermsInclude(IEnumerable<string> values)
-		{
-			Values = values;
-		}
+		/// <summary>
+		/// Creates an instance of <see cref="TermsInclude"/> that uses a collection of terms
+		/// to include in the response
+		/// </summary>
+		/// <param name="values">The exact terms to include</param>
+		public TermsInclude(IEnumerable<string> values) => Values = values;
 
+		/// <summary>
+		/// Creates an instance of <see cref="TermsInclude"/> that partitions the terms into a number of
+		/// partitions to receive in multiple requests. Used to process many unique terms
+		/// </summary>
+		/// <param name="partition">The 0-based partition number for this request</param>
+		/// <param name="numberOfPartitions">The total number of partitions</param>
 		public TermsInclude(long partition, long numberOfPartitions)
 		{
 			Partition = partition;

src/Nest/CommonAbstractions/Union/Union.cs

@@ -3,16 +3,36 @@
 
 namespace Nest
 {
+	/// <summary>
+	/// Represents the union of two types, <typeparamref name="TFirst"/> and <typeparamref name="TSecond"/>. Used
+	/// in scenarios where an Elasticsearch API may accept more than one different input data structure.
+	/// </summary>
+	/// <typeparam name="TFirst">The first type</typeparam>
+	/// <typeparam name="TSecond">The second type</typeparam>
 	[JsonConverter(typeof(UnionJsonConverter))]
 	public class Union<TFirst, TSecond>
 	{
 		internal readonly TFirst Item1;
 		internal readonly TSecond Item2;
 		internal readonly int _tag;
 
+		/// <summary>
+		/// Creates an new instance of <see cref="Union{TFirst,TSecond}"/> that encapsulates <paramref name="item"/> value
+		/// </summary>
+		/// <param name="item">The value to encapsulate</param>
 		public Union(TFirst item) { Item1 = item; _tag = 0; }
+
+		/// <summary>
+		/// Creates an new instance of <see cref="Union{TFirst,TSecond}"/> that encapsulates <paramref name="item"/> value
+		/// </summary>
+		/// <param name="item">The value to encapsulate</param>
 		public Union(TSecond item) { Item2 = item; _tag = 1; }
 
+		/// <summary>
+		/// Runs an <see cref="Action{T}"/> delegate against the encapsulated value
+		/// </summary>
+		/// <param name="first">The delegate to run when this instance encapsulates an instance of <typeparamref name="TFirst"/></param>
+		/// <param name="second">The delegate to run when this instance encapsulates an instance of <typeparamref name="TSecond"/></param>
 		public void Match(Action<TFirst> first, Action<TSecond> second)
 		{
 			switch (_tag)
@@ -26,6 +46,12 @@ public void Match(Action<TFirst> first, Action<TSecond> second)
 				default: throw new Exception($"Unrecognized tag value: {_tag}");
 			}
 		}
+
+		/// <summary>
+		/// Runs a <see cref="Func{T,TResult}"/> delegate against the encapsulated value
+		/// </summary>
+		/// <param name="first">The delegate to run when this instance encapsulates an instance of <typeparamref name="TFirst"/></param>
+		/// <param name="second">The delegate to run when this instance encapsulates an instance of <typeparamref name="TSecond"/></param>
 		public T Match<T>(Func<TFirst, T> first, Func<TSecond, T> second)
 		{
 			switch (_tag)

src/Nest/CommonAbstractions/Union/UnionJsonConverter.cs

@@ -15,8 +15,7 @@ internal class UnionJsonConverter : JsonConverter
 
 		public static UnionJsonConverterBase CreateConverter(Type t)
 		{
-			UnionJsonConverterBase conversion;
-			if (KnownTypes.TryGetValue(t, out conversion))
+			if (KnownTypes.TryGetValue(t, out var conversion))
 				return conversion;
 
 			var genericArguments = t.GetTypeInfo().GenericTypeArguments;
@@ -55,9 +54,11 @@ public bool TryRead<T>(JsonReader reader, JsonSerializer serializer, out T v)
 				v = serializer.Deserialize<T>(reader);
 				return true;
 			}
-			catch {}
-			v= default(T);
-			return false;
+			catch
+			{
+				v = default(T);
+				return false;
+			}
 		}
 
 		public abstract void WriteJson(JsonWriter writer, object v, JsonSerializer serializer);

src/Nest/Search/Search/SourceFiltering/SourceFilter.cs

@@ -29,7 +29,6 @@ public class SourceFilterDescriptor<T> : DescriptorBase<SourceFilterDescriptor<T
 
 		Fields ISourceFilter.Excludes { get; set; }
 
-
 		public SourceFilterDescriptor<T> Includes(Func<FieldsDescriptor<T>, IPromise<Fields>> fields) =>
 			Assign(a => a.Includes = fields?.Invoke(new FieldsDescriptor<T>())?.Value);