Document ResponseException and derived types

Author: sharwell

src/corelib/Core/Exceptions/Response/BadServiceRequestException.cs

@@ -1,16 +1,45 @@
 using System;
+using System.Net;
 using System.Runtime.Serialization;
 using RestResponse = JSIStudios.SimpleRESTServices.Client.Response;
 
 namespace net.openstack.Core.Exceptions.Response
 {
+    /// <summary>
+    /// Represents errors with status code <see cref="HttpStatusCode.BadRequest"/> resulting
+    /// from a call to a REST API.
+    /// </summary>
     [Serializable]
     public class BadServiceRequestException : ResponseException
     {
-        public BadServiceRequestException(RestResponse response) : base("Unable to process the service request.  Please try again later.", response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BadServiceRequestException"/> class with the
+        /// specified REST response.
+        /// </summary>
+        /// <param name="response">The REST response.</param>
+        public BadServiceRequestException(RestResponse response)
+            : base("Unable to process the service request.  Please try again later.", response)
+        {
+        }
 
-        public BadServiceRequestException(string message, RestResponse response) : base(message, response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BadServiceRequestException"/> class with the
+        /// specified error message and REST response.
+        /// </summary>
+        /// <param name="message">The message that describes the error.</param>
+        /// <param name="response">The REST response.</param>
+        public BadServiceRequestException(string message, RestResponse response)
+            : base(message, response)
+        {
+        }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BadServiceRequestException"/> class with
+        /// serialized data.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> that holds the serialized object data about the exception being thrown.</param>
+        /// <param name="context">The <see cref="StreamingContext"/> that contains contextual information about the source or destination.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="info"/> is <c>null</c>.</exception>
         protected BadServiceRequestException(SerializationInfo info, StreamingContext context)
             : base(info, context)
         {

src/corelib/Core/Exceptions/Response/ItemNotFoundException.cs

@@ -1,16 +1,45 @@
 using System;
+using System.Net;
 using System.Runtime.Serialization;
 using RestResponse = JSIStudios.SimpleRESTServices.Client.Response;
 
 namespace net.openstack.Core.Exceptions.Response
 {
+    /// <summary>
+    /// Represents errors with status code <see cref="HttpStatusCode.NotFound"/> resulting
+    /// from a call to a REST API.
+    /// </summary>
     [Serializable]
     public class ItemNotFoundException : ResponseException
     {
-        public ItemNotFoundException(RestResponse response) : base("The item was not found or does not exist.", response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ItemNotFoundException"/> class with the
+        /// specified REST response.
+        /// </summary>
+        /// <param name="response">The REST response.</param>
+        public ItemNotFoundException(RestResponse response)
+            : base("The item was not found or does not exist.", response)
+        {
+        }
 
-        public ItemNotFoundException(string message, RestResponse response) : base(message, response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ItemNotFoundException"/> class with the
+        /// specified error message and REST response.
+        /// </summary>
+        /// <param name="message">The message that describes the error.</param>
+        /// <param name="response">The REST response.</param>
+        public ItemNotFoundException(string message, RestResponse response)
+            : base(message, response)
+        {
+        }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ItemNotFoundException"/> class with
+        /// serialized data.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> that holds the serialized object data about the exception being thrown.</param>
+        /// <param name="context">The <see cref="StreamingContext"/> that contains contextual information about the source or destination.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="info"/> is <c>null</c>.</exception>
         protected ItemNotFoundException(SerializationInfo info, StreamingContext context)
             : base(info, context)
         {

src/corelib/Core/Exceptions/Response/MethodNotImplementedException.cs

@@ -1,16 +1,45 @@
 using System;
+using System.Net;
 using System.Runtime.Serialization;
 using RestResponse = JSIStudios.SimpleRESTServices.Client.Response;
 
 namespace net.openstack.Core.Exceptions.Response
 {
+    /// <summary>
+    /// Represents errors with status code <see cref="HttpStatusCode.NotImplemented"/> resulting
+    /// from a call to a REST API.
+    /// </summary>
     [Serializable]
     public class MethodNotImplementedException : ResponseException
     {
-        public MethodNotImplementedException(RestResponse response) : base("The requested method is not implemented at the service.", response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="MethodNotImplementedException"/> class with the
+        /// specified REST response.
+        /// </summary>
+        /// <param name="response">The REST response.</param>
+        public MethodNotImplementedException(RestResponse response)
+            : base("The requested method is not implemented at the service.", response)
+        {
+        }
 
-        public MethodNotImplementedException(string message, RestResponse response) : base(message, response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="MethodNotImplementedException"/> class with the
+        /// specified error message and REST response.
+        /// </summary>
+        /// <param name="message">The message that describes the error.</param>
+        /// <param name="response">The REST response.</param>
+        public MethodNotImplementedException(string message, RestResponse response)
+            : base(message, response)
+        {
+        }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="MethodNotImplementedException"/> class with
+        /// serialized data.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> that holds the serialized object data about the exception being thrown.</param>
+        /// <param name="context">The <see cref="StreamingContext"/> that contains contextual information about the source or destination.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="info"/> is <c>null</c>.</exception>
         protected MethodNotImplementedException(SerializationInfo info, StreamingContext context)
             : base(info, context)
         {

src/corelib/Core/Exceptions/Response/ResponseException.cs

@@ -6,11 +6,28 @@
 
 namespace net.openstack.Core.Exceptions.Response
 {
+    /// <summary>
+    /// Represents errors resulting from a call to a REST API.
+    /// </summary>
     [Serializable]
-    public class ResponseException : Exception
+    public abstract class ResponseException : Exception
     {
-        public RestResponse Response { get; private set; }
+        /// <summary>
+        /// Gets the REST <see cref="RestResponse"/> containing the details
+        /// about this error.
+        /// </summary>
+        public RestResponse Response
+        {
+            get;
+            private set;
+        }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ResponseException"/> class with the
+        /// specified error message and REST response.
+        /// </summary>
+        /// <param name="message">The message that describes the error.</param>
+        /// <param name="response">The REST response.</param>
         public ResponseException(string message, RestResponse response)
             : base(message)
         {
@@ -97,25 +114,38 @@ void ISerializable.GetObjectData(SerializationInfo info, StreamingContext contex
             }
         }
 
-        [DataContract]
+        [JsonObject(MemberSerialization.OptIn)]
         private sealed class ErrorDetails
         {
-            [DataMember(Name = "code")]
+#pragma warning disable 649 // Field '{fieldname}' is never assigned to, and will always have its default value {0 | null}
+            [JsonProperty("code")]
             public int Code;
 
-            [DataMember(Name = "message")]
+            [JsonProperty("message")]
             public string Message;
 
-            [DataMember(Name = "details")]
+            [JsonProperty("details")]
             public string Details;
+#pragma warning restore 649
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ResponseException"/> class with
+        /// serialized data.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> that holds the serialized object data about the exception being thrown.</param>
+        /// <param name="context">The <see cref="StreamingContext"/> that contains contextual information about the source or destination.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="info"/> is <c>null</c>.</exception>
         protected ResponseException(SerializationInfo info, StreamingContext context)
             : base(info, context)
         {
+            if (info == null)
+                throw new ArgumentNullException("info");
+
             Response = (RestResponse)info.GetValue("Response", typeof(RestResponse));
         }
 
+        /// <inheritdoc/>
         [SecurityCritical]
         public override void GetObjectData(SerializationInfo info, StreamingContext context)
         {

src/corelib/Core/Exceptions/Response/ServiceConflictException.cs

@@ -1,16 +1,45 @@
 using System;
+using System.Net;
 using System.Runtime.Serialization;
 using RestResponse = JSIStudios.SimpleRESTServices.Client.Response;
 
 namespace net.openstack.Core.Exceptions.Response
 {
+    /// <summary>
+    /// Represents errors with status code <see cref="HttpStatusCode.Conflict"/> resulting
+    /// from a call to a REST API.
+    /// </summary>
     [Serializable]
     public class ServiceConflictException : ResponseException
     {
-        public ServiceConflictException(RestResponse response) : base("There was a conflict with the service.  Entity may already exist.", response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ServiceConflictException"/> class with the
+        /// specified REST response.
+        /// </summary>
+        /// <param name="response">The REST response.</param>
+        public ServiceConflictException(RestResponse response)
+            : base("There was a conflict with the service. Entity may already exist.", response)
+        {
+        }
 
-        public ServiceConflictException(string message, RestResponse response) : base(message, response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ServiceConflictException"/> class with the
+        /// specified error message and REST response.
+        /// </summary>
+        /// <param name="message">The message that describes the error.</param>
+        /// <param name="response">The REST response.</param>
+        public ServiceConflictException(string message, RestResponse response)
+            : base(message, response)
+        {
+        }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ServiceConflictException"/> class with
+        /// serialized data.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> that holds the serialized object data about the exception being thrown.</param>
+        /// <param name="context">The <see cref="StreamingContext"/> that contains contextual information about the source or destination.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="info"/> is <c>null</c>.</exception>
         protected ServiceConflictException(SerializationInfo info, StreamingContext context)
             : base(info, context)
         {

src/corelib/Core/Exceptions/Response/ServiceFaultException.cs

@@ -1,16 +1,45 @@
 using System;
+using System.Net;
 using System.Runtime.Serialization;
 using RestResponse = JSIStudios.SimpleRESTServices.Client.Response;
 
 namespace net.openstack.Core.Exceptions.Response
 {
+    /// <summary>
+    /// Represents errors with status code <see cref="HttpStatusCode.InternalServerError"/> resulting
+    /// from a call to a REST API.
+    /// </summary>
     [Serializable]
     public class ServiceFaultException : ResponseException
     {
-        public ServiceFaultException(RestResponse response) : base("There was an unhandled error at the service endpoint.  Please try again later.", response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ServiceFaultException"/> class with the
+        /// specified REST response.
+        /// </summary>
+        /// <param name="response">The REST response.</param>
+        public ServiceFaultException(RestResponse response)
+            : base("There was an unhandled error at the service endpoint.  Please try again later.", response)
+        {
+        }
 
-        public ServiceFaultException(string message, RestResponse response) : base(message, response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ServiceFaultException"/> class with the
+        /// specified error message and REST response.
+        /// </summary>
+        /// <param name="message">The message that describes the error.</param>
+        /// <param name="response">The REST response.</param>
+        public ServiceFaultException(string message, RestResponse response)
+            : base(message, response)
+        {
+        }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ServiceFaultException"/> class with
+        /// serialized data.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> that holds the serialized object data about the exception being thrown.</param>
+        /// <param name="context">The <see cref="StreamingContext"/> that contains contextual information about the source or destination.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="info"/> is <c>null</c>.</exception>
         protected ServiceFaultException(SerializationInfo info, StreamingContext context)
             : base(info, context)
         {

src/corelib/Core/Exceptions/Response/ServiceLimitReachedException.cs

@@ -1,16 +1,45 @@
 using System;
+using System.Net;
 using System.Runtime.Serialization;
 using RestResponse = JSIStudios.SimpleRESTServices.Client.Response;
 
 namespace net.openstack.Core.Exceptions.Response
 {
+    /// <summary>
+    /// Represents errors with status code <see cref="HttpStatusCode.RequestEntityTooLarge"/> resulting
+    /// from a call to a REST API.
+    /// </summary>
     [Serializable]
     public class ServiceLimitReachedException : ResponseException
     {
-        public ServiceLimitReachedException(RestResponse response) : base("The service rate limit has been reached.  Either request a service limit increase or wait until the limit resets.", response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ServiceLimitReachedException"/> class with the
+        /// specified REST response.
+        /// </summary>
+        /// <param name="response">The REST response.</param>
+        public ServiceLimitReachedException(RestResponse response)
+            : base("The service rate limit has been reached. Either request a service limit increase or wait until the limit resets.", response)
+        {
+        }
 
-        public ServiceLimitReachedException(string message, RestResponse response) : base(message, response) { }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ServiceLimitReachedException"/> class with the
+        /// specified error message and REST response.
+        /// </summary>
+        /// <param name="message">The message that describes the error.</param>
+        /// <param name="response">The REST response.</param>
+        public ServiceLimitReachedException(string message, RestResponse response)
+            : base(message, response)
+        {
+        }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ServiceLimitReachedException"/> class with
+        /// serialized data.
+        /// </summary>
+        /// <param name="info">The <see cref="SerializationInfo"/> that holds the serialized object data about the exception being thrown.</param>
+        /// <param name="context">The <see cref="StreamingContext"/> that contains contextual information about the source or destination.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="info"/> is <c>null</c>.</exception>
         protected ServiceLimitReachedException(SerializationInfo info, StreamingContext context)
             : base(info, context)
         {