fix #2286 normalize ApiCall and CallDetails and add better xmldocs to IResponse (#2381)

Author: Mpdreamz

src/Elasticsearch.Net/Responses/IBodyWithApiCallDetails.cs

@@ -1,7 +1,14 @@
 namespace Elasticsearch.Net
 {
+	/// <summary>
+	/// Implementing this interface on your response objects will cause the low level client to
+	/// automatically set <see cref="IApiCallDetails"/> diagnostic information on the object.
+	/// </summary>
 	public interface IBodyWithApiCallDetails
 	{
-		IApiCallDetails CallDetails { get; set; }
+		/// <summary>
+		/// Sets and returns the <see cref="IApiCallDetails"/> diagnostic information
+		/// </summary>
+		IApiCallDetails ApiCall { get; set; }
 	}
-}
+}

src/Elasticsearch.Net/Transport/Pipeline/ResponseBuilder.cs

@@ -125,7 +125,7 @@ private void Finalize(ElasticsearchResponse<TReturn> response)
 			var passAlongConnectionStatus = response.Body as IBodyWithApiCallDetails;
 			if (passAlongConnectionStatus != null)
 			{
-				passAlongConnectionStatus.CallDetails = response;
+				passAlongConnectionStatus.ApiCall = response;
 			}
 		}
 

src/Nest/CommonAbstractions/Response/ResponseBase.cs

@@ -7,37 +7,67 @@
 
 namespace Nest
 {
+	/// <summary>
+	/// Shared interface by all elasticsearch responses
+	/// </summary>
 	public interface IResponse : IBodyWithApiCallDetails
 	{
+		/// <summary>
+		/// This property can be used to check if a response is functionally valid or not.
+		/// This is a NEST abstraction to have a single point to check whether something wrong happend with the request.
+		/// <para>For instance an elasticsearch bulk response always returns 200 and individual bulk items may fail, <see cref="IsValid"/> will be false in that case</para>
+		/// <para>You can also configure the client to always throw an <see cref="ElasticsearchClientException"/> using <see cref="IConnectionConfigurationValues.ThrowExceptions"/> if the response is not valid</para>
+		/// </summary>
 		[JsonIgnore]
 		bool IsValid { get; }
 
+		/// <summary>
+		/// Returns the <see cref="IApiCallDetails"/> diagnostic information
+		/// </summary>
 		[JsonIgnore]
-		IApiCallDetails ApiCall { get; }
+		new IApiCallDetails ApiCall { get; }
 
+		/// <summary>
+		/// If the response results in an error on elasticsearch's side an <pre>error</pre> element will be returned, this is mapped to <see cref="ServerError"/> in NEST.
+		/// <para>This property is a shortcut to <see cref="ApiCall"/>'s <see cref="IApiCallDetails.ServerError"/> and is possibly set when <see cref="IsValid"/> is false depending on the cause of the error</para>
+		/// <para>You can also configure the client to always throw an <see cref="ElasticsearchClientException"/> using <see cref="IConnectionConfigurationValues.ThrowExceptions"/> if the response is not valid</para>
+		/// </summary>
 		[JsonIgnore]
 		ServerError ServerError { get; }
 
+		/// <summary>
+		/// If the request resulted in an exception on the client side this will hold the exception that was thrown.
+		/// <para>This property is a shortcut to <see cref="ApiCall"/>'s <see cref="IApiCallDetails.OriginalException"/> and is possibly set when <see cref="IsValid"/> is false depending on the cause of the error</para>
+		/// <para>You can also configure the client to always throw an <see cref="ElasticsearchClientException"/> using <see cref="IConnectionConfigurationValues.ThrowExceptions"/> if the response is not valid</para>
+		/// </summary>
 		[JsonIgnore]
 		Exception OriginalException { get; }
 
+		/// <summary>
+		/// A lazy human readable string representation of what happened during this request for both succesful and failed requests, very useful while developing or to log when you get <see cref="IsValid"/> = false responses.
+		/// </summary>
 		[JsonIgnore]
 		string DebugInformation { get; }
 
 	}
 
 	public abstract class ResponseBase : IResponse
 	{
+		/// <inheritdoc/>
 		public virtual bool IsValid => (this.ApiCall?.Success ?? false) && (this.ServerError == null);
 
-		IApiCallDetails IBodyWithApiCallDetails.CallDetails { get; set; }
+		IApiCallDetails IBodyWithApiCallDetails.ApiCall { get; set; }
 
-		public virtual IApiCallDetails ApiCall => ((IBodyWithApiCallDetails)this).CallDetails;
+		/// <inheritdoc/>
+		public virtual IApiCallDetails ApiCall => ((IBodyWithApiCallDetails)this).ApiCall;
 
+		/// <inheritdoc/>
 		public virtual ServerError ServerError => this.ApiCall?.ServerError;
 
+		/// <inheritdoc/>
 		public Exception OriginalException => this.ApiCall?.OriginalException;
 
+		/// <inheritdoc/>
 		public string DebugInformation
 		{
 			get

src/Nest/ElasticClient.cs

@@ -85,7 +85,7 @@ private static TResponse CreateInvalidInstance<TResponse>(IApiCallDetails respon
 			where TResponse : ResponseBase
 		{
 			var r = typeof(TResponse).CreateInstance<TResponse>();
-			((IBodyWithApiCallDetails)r).CallDetails = response;
+			((IBodyWithApiCallDetails)r).ApiCall = response;
 			return r;
 		}
 

src/Nest/Search/MultiSearch/MultiSearchResponse.cs

@@ -24,7 +24,7 @@ protected override void DebugIsValid(StringBuilder sb)
 				sb.AppendLine($"  search[{i.i}]: {i.item}");
 		}
 
-		[JsonConverter(typeof(VerbatimDictionaryKeysJsonConverter))]	
+		[JsonConverter(typeof(VerbatimDictionaryKeysJsonConverter))]
 		internal IDictionary<string, object> Responses { get; set; }
 
 		public int TotalResponses => this.Responses.HasAny() ? this.Responses.Count() : 0;
@@ -33,7 +33,7 @@ private IEnumerable<T> _allResponses<T>() where T : class, IResponse, IBodyWithA
 		{
 			foreach (var r in this.Responses.Values.OfType<T>())
 			{
-				r.CallDetails = this.ApiCall;
+				((IBodyWithApiCallDetails)r).ApiCall = this.ApiCall;
 				yield return r;
 			}
 		}
@@ -50,7 +50,7 @@ public SearchResponse<T> GetResponse<T>(string name) where T : class
 			this.Responses.TryGetValue(name, out response);
 			var r = response as IBodyWithApiCallDetails;
 			if (r != null)
-				r.CallDetails = this.ApiCall;
+				r.ApiCall = this.ApiCall;
 			return response as SearchResponse<T>;
 		}
 	}

src/Nest/Search/Percolator/MultiPercolate/MultiPercolateResponse.cs

@@ -37,7 +37,7 @@ private IEnumerable<PercolateResponse> _allResponses()
 			foreach (var r in this.AllResponses)
 			{
 				IBodyWithApiCallDetails d = r;
-				d.CallDetails = this.ApiCall;
+				d.ApiCall = this.ApiCall;
 				yield return r;
 			}
 		}

src/Profiling/Async/IndexAsyncOperation.cs

@@ -21,7 +21,7 @@ public override async Task ProfileAsync(IElasticClient client, ColoredConsoleWri
 					await client.IndexAsync(Developer.Generator.Generate(), d => d.Index<Developer>()).ConfigureAwait(false);
 
 				if (!indexResponse.IsValid)
-					output.WriteOrange($"error with id {indexResponse.Id}. message: {indexResponse.CallDetails.OriginalException}");
+					output.WriteOrange($"error with id {indexResponse.Id}. message: {indexResponse.ApiCall.OriginalException}");
 			}
 		}
 	}

src/Profiling/Async/SearchAsyncOperation.cs

@@ -23,7 +23,7 @@ public override async Task SetupAsync(IElasticClient client, ColoredConsoleWrite
 			var indexResponse = await client.IndexAsync(_developer, d => d.Index<Developer>().Refresh(Refresh.True)).ConfigureAwait(false);
 
 			if (!indexResponse.IsValid)
-				output.WriteOrange($"error with id {indexResponse.Id}. message: {indexResponse.CallDetails.OriginalException}");
+				output.WriteOrange($"error with id {indexResponse.Id}. message: {indexResponse.ApiCall.OriginalException}");
 		}
 
 		public override async Task ProfileAsync(IElasticClient client, ColoredConsoleWriter output)
@@ -46,7 +46,7 @@ public override async Task ProfileAsync(IElasticClient client, ColoredConsoleWri
 
 				if (!searchResponse.IsValid)
 					output.WriteOrange(
-						$"error searching for {nameof(Developer)}. message: {searchResponse.CallDetails.OriginalException}");
+						$"error searching for {nameof(Developer)}. message: {searchResponse.ApiCall.OriginalException}");
 
 				if (!searchResponse.Documents.Any())
 					output.WriteOrange($"did not find matching {nameof(Developer)} for search.");
@@ -58,7 +58,7 @@ public override async Task TeardownAsync(IElasticClient client, ColoredConsoleWr
 			var deleteResponse = await client.DeleteAsync<Developer>(_developer, d => d.Index<Developer>()).ConfigureAwait(false);
 
 			if (!deleteResponse.IsValid)
-				output.WriteOrange($"error with id {deleteResponse.Id}. message: {deleteResponse.CallDetails.OriginalException}");
+				output.WriteOrange($"error with id {deleteResponse.Id}. message: {deleteResponse.ApiCall.OriginalException}");
 		}
 	}
 }

src/Tests/ClientConcepts/Exceptions/ExceptionTests.cs

@@ -62,10 +62,10 @@ public void ServerTestWhenThrowExceptionsDisabled()
 			// HttpClient does not throw on "known error" status codes (i.e. 404) thus OriginalException should not be set
 			response.CallDetails.OriginalException.Should().BeNull();
 #else
-			response.CallDetails.OriginalException.Should().NotBeNull();
+			response.ApiCall.OriginalException.Should().NotBeNull();
 #endif
-			response.CallDetails.ServerError.Should().NotBeNull();
-			response.CallDetails.ServerError.Status.Should().BeGreaterThan(0);
+			response.ApiCall.ServerError.Should().NotBeNull();
+			response.ApiCall.ServerError.Status.Should().BeGreaterThan(0);
 		}
 
 		//[I]
@@ -78,9 +78,9 @@ public void ClientTestWhenThrowExceptionsDisabled()
 			// HttpClient does not throw on "known error" status codes (i.e. 404) thus OriginalException should not be set
 			response.CallDetails.OriginalException.Should().BeNull();
 #else
-			response.CallDetails.OriginalException.Should().NotBeNull();
+			response.ApiCall.OriginalException.Should().NotBeNull();
 #endif
-			response.CallDetails.ServerError.Should().BeNull();
+			response.ApiCall.ServerError.Should().BeNull();
 		}
 
 		//TODO figure out a way to trigger this again

src/Tests/Framework/EndpointTests/ApiIntegrationTestBase.cs

@@ -44,10 +44,10 @@ protected override Task AssertOnAllResponses(Action<TResponse> assert)
 
 			return base.AssertOnAllResponses((r) =>
 			{
-				if (TestClient.Configuration.RunIntegrationTests && !r.IsValid && r.CallDetails.OriginalException != null
-					&& IsNotRequestExceptionType(r.CallDetails.OriginalException.GetType()))
+				if (TestClient.Configuration.RunIntegrationTests && !r.IsValid && r.ApiCall.OriginalException != null
+					&& IsNotRequestExceptionType(r.ApiCall.OriginalException.GetType()))
 				{
-					ExceptionDispatchInfo.Capture(r.CallDetails.OriginalException).Throw();
+					ExceptionDispatchInfo.Capture(r.ApiCall.OriginalException).Throw();
 					return;
 				}