Issue 669 - added Exception xml doc comments (Azure#1076)

* Added exception doc comments to generated CSharp code for known exceptions

* Added test for CodeWriter to verify it writes exception doc comments

* Regenerated CSharp test expected and samples

AutoRest/AutoRest.Core.Tests/CodeGeneratorsTests.cs

@@ -55,6 +55,18 @@ public void CodeWriterWrapsComments()
         /// and there is a sun outside the window."));
         }
 
+        [Fact]
+        public void CodeWriterWritesCRefAttribute()
+        {
+            var sampleModelTemplate = new SampleModel();
+            var sampleViewModel = new SampleViewModel();
+
+            sampleModelTemplate.Model = sampleViewModel;
+            var output = sampleModelTemplate.ToString();
+            Assert.True(output.Contains("/// <exception cref=\"CloudException\">"));
+            Assert.True(output.Contains("/// <exception cref=\"ArgumentNullException\">"));
+        }
+
         [Fact]
         public void CodeWriterOverwritesExistingFile()
         {

AutoRest/AutoRest.Core.Tests/Resource/SampleViewModel.cs

@@ -30,6 +30,10 @@ public string Name
             get { return "CacheSku"; }
         }
 
+        public string OperationExceptionTypeString
+        {
+            get { return "CloudException"; }
+        }
         public string SerializationBlock
         {
             get { return @"if (outputObject == null)

AutoRest/AutoRest.Core.Tests/Templates/SampleModel.cshtml

@@ -4,6 +4,8 @@ using System.Collection;
 @Model.Imports
 namespace @Model.Namespace
 {
+    @using System;
+
     public partial class @Model.Name
     {
         @foreach(var property in Model.Properties)
@@ -15,6 +17,12 @@ namespace @Model.Namespace
         /// <summary>
         /// Serialize the object
         /// </summary>
+        /// <exception cref="@(Model.OperationExceptionTypeString)">
+        /// Test exception comment
+        /// </exception>
+        /// <exception cref="ArgumentNullException">
+        /// Test exception comment two
+        /// </exception>
         /// <returns>
         /// Returns the json model for the type @Model.Name
         /// </returns>

AutoRest/AutoRest.Core/Template.cs

@@ -50,6 +50,31 @@ public string EmptyLine
         /// </summary>
         public abstract Task ExecuteAsync();
 
+        /// <summary>
+        /// Write the attribute string directly to the output
+        /// </summary>
+        /// <param name="attribute"></param>
+        /// <param name="tuple1"></param>
+        /// <param name="tuple2"></param>
+        /// <param name="tuple3"></param>
+        protected void WriteAttribute(string attribute,
+                                     Tuple<string, int> tuple1,
+                                     Tuple<string, int> tuple2,
+                                     Tuple<Tuple<string, int>, Tuple<object, int>, bool> tuple3)
+        {
+            string value = string.Empty;
+
+            if (attribute == "cref")
+            {
+                value = string.Format(CultureInfo.InvariantCulture, "{0}{1}{2}", tuple1?.Item1, tuple3?.Item2?.Item1.ToString(), tuple2?.Item1);
+            }
+            else
+            {
+                throw new NotImplementedException(attribute + " attributes are not yet implemented");
+            }
+            WriteLiteral(value);
+        }
+
         /// <summary>
         /// Write the given value directly to the output
         /// </summary>

AutoRest/Generators/CSharp/Azure.CSharp.Tests/Expected/AcceptanceTests/AzureBodyDuration/AutoRestDurationTestService.cs

@@ -106,6 +106,9 @@ protected AutoRestDurationTestService(HttpClientHandler rootHandler, params Dele
         /// <param name='handlers'>
         /// Optional. The delegating handlers to add to the http client pipeline.
         /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown when a required parameter is null
+        /// </exception>
         protected AutoRestDurationTestService(Uri baseUri, params DelegatingHandler[] handlers) : this(handlers)
         {
             if (baseUri == null)
@@ -127,6 +130,9 @@ protected AutoRestDurationTestService(Uri baseUri, params DelegatingHandler[] ha
         /// <param name='handlers'>
         /// Optional. The delegating handlers to add to the http client pipeline.
         /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown when a required parameter is null
+        /// </exception>
         protected AutoRestDurationTestService(Uri baseUri, HttpClientHandler rootHandler, params DelegatingHandler[] handlers) : this(rootHandler, handlers)
         {
             if (baseUri == null)
@@ -145,6 +151,9 @@ protected AutoRestDurationTestService(Uri baseUri, HttpClientHandler rootHandler
         /// <param name='handlers'>
         /// Optional. The delegating handlers to add to the http client pipeline.
         /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown when a required parameter is null
+        /// </exception>
         public AutoRestDurationTestService(ServiceClientCredentials credentials, params DelegatingHandler[] handlers) : this(handlers)
         {
             if (credentials == null)
@@ -170,6 +179,9 @@ public AutoRestDurationTestService(ServiceClientCredentials credentials, params
         /// <param name='handlers'>
         /// Optional. The delegating handlers to add to the http client pipeline.
         /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown when a required parameter is null
+        /// </exception>
         public AutoRestDurationTestService(ServiceClientCredentials credentials, HttpClientHandler rootHandler, params DelegatingHandler[] handlers) : this(rootHandler, handlers)
         {
             if (credentials == null)
@@ -195,6 +207,9 @@ public AutoRestDurationTestService(ServiceClientCredentials credentials, HttpCli
         /// <param name='handlers'>
         /// Optional. The delegating handlers to add to the http client pipeline.
         /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown when a required parameter is null
+        /// </exception>
         public AutoRestDurationTestService(Uri baseUri, ServiceClientCredentials credentials, params DelegatingHandler[] handlers) : this(handlers)
         {
             if (baseUri == null)
@@ -228,6 +243,9 @@ public AutoRestDurationTestService(Uri baseUri, ServiceClientCredentials credent
         /// <param name='handlers'>
         /// Optional. The delegating handlers to add to the http client pipeline.
         /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown when a required parameter is null
+        /// </exception>
         public AutoRestDurationTestService(Uri baseUri, ServiceClientCredentials credentials, HttpClientHandler rootHandler, params DelegatingHandler[] handlers) : this(rootHandler, handlers)
         {
             if (baseUri == null)

AutoRest/Generators/CSharp/Azure.CSharp.Tests/Expected/AcceptanceTests/AzureBodyDuration/DurationOperations.cs

@@ -35,6 +35,9 @@ internal partial class DurationOperations : IServiceOperations<AutoRestDurationT
         /// <param name='client'>
         /// Reference to the service client.
         /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown when a required parameter is null
+        /// </exception>
         internal DurationOperations(AutoRestDurationTestService client)
         {
             if (client == null) 
@@ -58,6 +61,12 @@ internal DurationOperations(AutoRestDurationTestService client)
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
+        /// <exception cref="SerializationException">
+        /// Thrown when unable to deserialize the response
+        /// </exception>
         /// <return>
         /// A response object containing the response body and response headers.
         /// </return>
@@ -206,6 +215,9 @@ internal DurationOperations(AutoRestDurationTestService client)
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
         /// <return>
         /// A response object containing the response body and response headers.
         /// </return>
@@ -338,6 +350,12 @@ internal DurationOperations(AutoRestDurationTestService client)
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
+        /// <exception cref="SerializationException">
+        /// Thrown when unable to deserialize the response
+        /// </exception>
         /// <return>
         /// A response object containing the response body and response headers.
         /// </return>
@@ -484,6 +502,12 @@ internal DurationOperations(AutoRestDurationTestService client)
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
+        /// <exception cref="SerializationException">
+        /// Thrown when unable to deserialize the response
+        /// </exception>
         /// <return>
         /// A response object containing the response body and response headers.
         /// </return>

AutoRest/Generators/CSharp/Azure.CSharp.Tests/Expected/AcceptanceTests/AzureBodyDuration/IDurationOperations.cs

@@ -31,6 +31,12 @@ public partial interface IDurationOperations
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
+        /// <exception cref="SerializationException">
+        /// Thrown when unable to deserialize the response
+        /// </exception>
         Task<AzureOperationResponse<TimeSpan?>> GetNullWithHttpMessagesAsync(Dictionary<string, List<string>> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken));
         /// <summary>
         /// Put a positive duration value
@@ -43,6 +49,9 @@ public partial interface IDurationOperations
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
         Task<AzureOperationResponse> PutPositiveDurationWithHttpMessagesAsync(TimeSpan durationBody, Dictionary<string, List<string>> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken));
         /// <summary>
         /// Get a positive duration value
@@ -53,6 +62,12 @@ public partial interface IDurationOperations
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
+        /// <exception cref="SerializationException">
+        /// Thrown when unable to deserialize the response
+        /// </exception>
         Task<AzureOperationResponse<TimeSpan?>> GetPositiveDurationWithHttpMessagesAsync(Dictionary<string, List<string>> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken));
         /// <summary>
         /// Get an invalid duration value
@@ -63,6 +78,12 @@ public partial interface IDurationOperations
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
+        /// <exception cref="SerializationException">
+        /// Thrown when unable to deserialize the response
+        /// </exception>
         Task<AzureOperationResponse<TimeSpan?>> GetInvalidWithHttpMessagesAsync(Dictionary<string, List<string>> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken));
     }
 }

AutoRest/Generators/CSharp/Azure.CSharp.Tests/Expected/AcceptanceTests/AzureBodyDuration/Models/ErrorException.cs

@@ -81,6 +81,9 @@ protected ErrorException(SerializationInfo info, StreamingContext context)
         /// </summary>
         /// <param name="info">Serialization info.</param>
         /// <param name="context">Streaming context.</param>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown when a required parameter is null
+        /// </exception>
         [SecurityPermission(SecurityAction.Demand, SerializationFormatter = true)]
         public override void GetObjectData(SerializationInfo info, StreamingContext context)
         {

AutoRest/Generators/CSharp/Azure.CSharp.Tests/Expected/AcceptanceTests/AzureCompositeModelClient/ArrayOperations.cs

@@ -35,6 +35,9 @@ internal partial class ArrayOperations : IServiceOperations<AzureCompositeModel>
         /// <param name='client'>
         /// Reference to the service client.
         /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown when a required parameter is null
+        /// </exception>
         internal ArrayOperations(AzureCompositeModel client)
         {
             if (client == null) 
@@ -58,6 +61,12 @@ internal ArrayOperations(AzureCompositeModel client)
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
+        /// <exception cref="SerializationException">
+        /// Thrown when unable to deserialize the response
+        /// </exception>
         /// <return>
         /// A response object containing the response body and response headers.
         /// </return>
@@ -206,6 +215,9 @@ internal ArrayOperations(AzureCompositeModel client)
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
         /// <return>
         /// A response object containing the response body and response headers.
         /// </return>
@@ -346,6 +358,12 @@ internal ArrayOperations(AzureCompositeModel client)
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
+        /// <exception cref="SerializationException">
+        /// Thrown when unable to deserialize the response
+        /// </exception>
         /// <return>
         /// A response object containing the response body and response headers.
         /// </return>
@@ -494,6 +512,9 @@ internal ArrayOperations(AzureCompositeModel client)
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
         /// <return>
         /// A response object containing the response body and response headers.
         /// </return>
@@ -635,6 +656,12 @@ internal ArrayOperations(AzureCompositeModel client)
         /// <param name='cancellationToken'>
         /// The cancellation token.
         /// </param>
+        /// <exception cref="ErrorException">
+        /// Thrown when the operation returned an invalid status code
+        /// </exception>
+        /// <exception cref="SerializationException">
+        /// Thrown when unable to deserialize the response
+        /// </exception>
         /// <return>
         /// A response object containing the response body and response headers.
         /// </return>