Add note about filter_path and deserialization (#3379)

This commit adds a note to the filter_path XML comments to warn about
response filtering potentially affecting deserialization to the respective response type.

Include XML comments on common options for Descriptor types

Closes #3331

Author: russcam

src/CodeGeneration/ApiGenerator/Domain/ApiQueryParameters.cs

@@ -101,6 +101,12 @@ public IEnumerable<string> DescriptionHighLevel
 					case "_source":
 						yield return "Whether the _source should be included in the response.";
 						yield break;
+					case "filter_path":
+						yield return this.Description;
+						yield return "<para>Use of response filtering can result in a response from Elasticsearch ";
+						yield return "that cannot be correctly deserialized to the respective response type for the request. ";
+						yield return "In such situations, use the low level client to issue the request and handle response deserialization</para>";
+						yield break;
 					default:
 						yield return this.Description;
 						yield break;

src/CodeGeneration/ApiGenerator/RestSpecification/Core/_common.json

@@ -23,7 +23,7 @@
     },
     "filter_path": {
       "type": "list",
-      "description": "A comma-separated list of filters used to reduce the respone."
+      "description": "A comma-separated list of filters used to reduce the response."
     }
   }
 }

src/CodeGeneration/ApiGenerator/Views/_Descriptors.Generated.cshtml

@@ -24,8 +24,9 @@ namespace Nest
 		var original = common.QueryStringKey;
 		var t = @common.TypeHighLevel;
 		var tSuffix = (t == "bool" || t == "bool?") ? " = true" : "";
-		<text>		public TDescriptor @(common.ClsName)(@common.TypeHighLevel @common.ClsArgumentName@tSuffix) => Qs("@original", @(common.ClsArgumentName));
-		</text>
+<text>		///<summary>@(Raw(string.Join("", common.DescriptionHighLevel)))</summary>
+		public TDescriptor @(common.ClsName)(@common.TypeHighLevel @common.ClsArgumentName@tSuffix) => Qs("@original", @(common.ClsArgumentName));
+</text>
 	}
 	}
 	@foreach (CsharpMethod method in Model.CsharpMethodsWithQueryStringInfo)

src/Nest/CommonAbstractions/Request/RequestBase.cs

@@ -81,6 +81,9 @@ public IRequestConfiguration RequestConfiguration
 		}
 	}
 
+	///<summary>
+	/// Base class for all Request descriptor types
+	///</summary>
 	public abstract partial class RequestDescriptorBase<TDescriptor, TParameters, TInterface> : RequestBase<TParameters>, IDescriptor
 		where TDescriptor : RequestDescriptorBase<TDescriptor, TParameters, TInterface>, TInterface
 		where TParameters : RequestParameters<TParameters>, new()

src/Nest/_Generated/_Descriptors.generated.cs

@@ -12,11 +12,15 @@ namespace Nest
 {
 	public abstract partial class RequestDescriptorBase<TDescriptor, TParameters, TInterface>
 	{
+		///<summary>Pretty format the returned JSON response.</summary>
 		public TDescriptor Pretty(bool? pretty = true) => Qs("pretty", pretty);
-				public TDescriptor Human(bool? human = true) => Qs("human", human);
-				public TDescriptor ErrorTrace(bool? errorTrace = true) => Qs("error_trace", errorTrace);
-				public TDescriptor FilterPath(string[] filterPath) => Qs("filter_path", filterPath);
-			}
+		///<summary>Return human readable values for statistics.</summary>
+		public TDescriptor Human(bool? human = true) => Qs("human", human);
+		///<summary>Include the stack trace of returned errors.</summary>
+		public TDescriptor ErrorTrace(bool? errorTrace = true) => Qs("error_trace", errorTrace);
+		///<summary>A comma-separated list of filters used to reduce the response.<para>Use of response filtering can result in a response from Elasticsearch that cannot be correctly deserialized to the respective response type for the request. In such situations, use the low level client to issue the request and handle response deserialization</para></summary>
+		public TDescriptor FilterPath(string[] filterPath) => Qs("filter_path", filterPath);
+	}
 
 	///<summary>descriptor for Bulk <pre>http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-bulk.html</pre></summary>
 	public partial class BulkDescriptor  : RequestDescriptorBase<BulkDescriptor,BulkRequestParameters, IBulkRequest>, IBulkRequest

src/Nest/_Generated/_Requests.generated.cs

@@ -20,7 +20,12 @@ public abstract partial class PlainRequestBase<TParameters>
 		public bool? Human { get => Q<bool?>("human"); set => Q("human", value); }
 		///<summary>Include the stack trace of returned errors.</summary>
 		public bool? ErrorTrace { get => Q<bool?>("error_trace"); set => Q("error_trace", value); }
-		///<summary>A comma-separated list of filters used to reduce the respone.</summary>
+		///<summary>
+		/// A comma-separated list of filters used to reduce the response.
+		/// <para>Use of response filtering can result in a response from Elasticsearch
+		/// that cannot be correctly deserialized to the respective response type for the request.
+		/// In such situations, use the low level client to issue the request and handle response deserialization</para>
+		///</summary>
 		public string[] FilterPath { get => Q<string[]>("filter_path"); set => Q("filter_path", value); }
 	}