Improve support for "Summary" and "Description" documentation fields (A…

…zure#1163)

* Increase support for "Summary" and "Description"

 - Fix bug where Indentation parameter of Template.cs
   counted text after the indentation too.
 - Update PetStore sample slightly.
 - Add support for "Title" field in JSON entities (which maps onto "Summary" field)

* Regenerate samples

* Regenerate tests

AutoRest/AutoRest.Core/ClientModel/CompositeType.cs

@@ -57,6 +57,11 @@ public IEnumerable<Property> ComposedProperties
         /// </summary>
         public string PolymorphicDiscriminator { get; set; }
 
+        /// <summary>
+        /// Gets or sets the summary.
+        /// </summary>
+        public string Summary { get; set; }
+
         /// <summary>
         /// Gets or sets the CompositeType documentation.
         /// </summary>

AutoRest/AutoRest.Core/ClientModel/Property.cs

@@ -62,6 +62,11 @@ public Property()
         /// </summary>
         public Dictionary<Constraint, string> Constraints { get; private set; }
 
+        /// <summary>
+        /// Gets or sets the summary.
+        /// </summary>
+        public string Summary { get; set; }
+
         /// <summary>
         /// Gets or sets the documentation.
         /// </summary>

AutoRest/AutoRest.Core/Template.cs

@@ -247,7 +247,8 @@ protected string Indentation
                         break;
                     }
                 }
-                return _lastLiteral.Substring(lineStart, _lastLiteral.Length - lineStart);
+                string latestLine = _lastLiteral.Substring(lineStart, _lastLiteral.Length - lineStart);
+                return new string(latestLine.TakeWhile(char.IsWhiteSpace).ToArray());
             }
         }
 

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

@@ -360,10 +360,12 @@ private void Initialize()
         /// <summary>
         /// Product Types
         /// </summary>
+        /// <remarks>
         /// The Products endpoint returns information about the Uber products offered
         /// at a given location. The response includes the display name and other
         /// details about each product, and lists the products in the proper display
         /// order.
+        /// </remarks>
         /// <param name='resourceGroupName'>
         /// Resource Group ID.
         /// </param>
@@ -535,7 +537,9 @@ public async Task<AzureOperationResponse<CatalogArray>> ListWithHttpMessagesAsyn
         /// <summary>
         /// Create products
         /// </summary>
+        /// <remarks>
         /// Resets products.
+        /// </remarks>
         /// <param name='subscriptionId'>
         /// Subscription ID.
         /// </param>
@@ -730,7 +734,9 @@ public async Task<AzureOperationResponse<CatalogDictionary>> CreateWithHttpMessa
         /// <summary>
         /// Update products
         /// </summary>
+        /// <remarks>
         /// Resets products.
+        /// </remarks>
         /// <param name='subscriptionId'>
         /// Subscription ID.
         /// </param>

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

@@ -25,10 +25,12 @@ public static partial class AzureCompositeModelExtensions
             /// <summary>
             /// Product Types
             /// </summary>
+            /// <remarks>
             /// The Products endpoint returns information about the Uber products offered
             /// at a given location. The response includes the display name and other
             /// details about each product, and lists the products in the proper display
             /// order.
+            /// </remarks>
             /// <param name='operations'>
             /// The operations group for this extension method.
             /// </param>
@@ -43,10 +45,12 @@ public static CatalogArray List(this IAzureCompositeModel operations, string res
             /// <summary>
             /// Product Types
             /// </summary>
+            /// <remarks>
             /// The Products endpoint returns information about the Uber products offered
             /// at a given location. The response includes the display name and other
             /// details about each product, and lists the products in the proper display
             /// order.
+            /// </remarks>
             /// <param name='operations'>
             /// The operations group for this extension method.
             /// </param>
@@ -67,7 +71,9 @@ public static async Task<CatalogArray> ListAsync(this IAzureCompositeModel opera
             /// <summary>
             /// Create products
             /// </summary>
+            /// <remarks>
             /// Resets products.
+            /// </remarks>
             /// <param name='operations'>
             /// The operations group for this extension method.
             /// </param>
@@ -88,7 +94,9 @@ public static CatalogDictionary Create(this IAzureCompositeModel operations, str
             /// <summary>
             /// Create products
             /// </summary>
+            /// <remarks>
             /// Resets products.
+            /// </remarks>
             /// <param name='operations'>
             /// The operations group for this extension method.
             /// </param>
@@ -115,7 +123,9 @@ public static async Task<CatalogDictionary> CreateAsync(this IAzureCompositeMode
             /// <summary>
             /// Update products
             /// </summary>
+            /// <remarks>
             /// Resets products.
+            /// </remarks>
             /// <param name='operations'>
             /// The operations group for this extension method.
             /// </param>
@@ -136,7 +146,9 @@ public static CatalogArray Update(this IAzureCompositeModel operations, string s
             /// <summary>
             /// Update products
             /// </summary>
+            /// <remarks>
             /// Resets products.
+            /// </remarks>
             /// <param name='operations'>
             /// The operations group for this extension method.
             /// </param>

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

@@ -110,10 +110,12 @@ public partial interface IAzureCompositeModel : IDisposable
             /// <summary>
         /// Product Types
         /// </summary>
+        /// <remarks>
         /// The Products endpoint returns information about the Uber products
         /// offered at a given location. The response includes the display
         /// name and other details about each product, and lists the products
         /// in the proper display order.
+        /// </remarks>
         /// <param name='resourceGroupName'>
         /// Resource Group ID.
         /// </param>
@@ -128,7 +130,9 @@ public partial interface IAzureCompositeModel : IDisposable
         /// <summary>
         /// Create products
         /// </summary>
+        /// <remarks>
         /// Resets products.
+        /// </remarks>
         /// <param name='subscriptionId'>
         /// Subscription ID.
         /// </param>
@@ -149,7 +153,9 @@ public partial interface IAzureCompositeModel : IDisposable
         /// <summary>
         /// Update products
         /// </summary>
+        /// <remarks>
         /// Resets products.
+        /// </remarks>
         /// <param name='subscriptionId'>
         /// Subscription ID.
         /// </param>

AutoRest/Generators/CSharp/Azure.CSharp/Templates/AzureMethodTemplate.cshtml

@@ -26,7 +26,9 @@ if (!string.IsNullOrWhiteSpace(Model.ExternalDocsUrl))
 }
 if (!String.IsNullOrEmpty(Model.Description) && !String.IsNullOrEmpty(Model.Summary))
 {
+@:/// <remarks>
 @:@WrapComment("/// ", Model.Description.EscapeXmlComment())
+@:/// </remarks>
 }
 foreach (var parameter in Model.LocalParameters)
 {
@@ -65,7 +67,9 @@ if (!string.IsNullOrWhiteSpace(Model.ExternalDocsUrl))
 }
 if (!String.IsNullOrEmpty(Model.Description) && !String.IsNullOrEmpty(Model.Summary))
 {
+@:/// <remarks>
 @:@WrapComment("/// ", Model.Description.EscapeXmlComment())
+@:/// </remarks>
 }
 foreach (var parameter in Model.LocalParameters)
 {

AutoRest/Generators/CSharp/CSharp.Tests/Expected/Mirror.Polymorphic/IPolymorphicAnimalStore.cs

@@ -41,10 +41,12 @@ public partial interface IPolymorphicAnimalStore : IDisposable
             /// <summary>
         /// Product Types
         /// </summary>
+        /// <remarks>
         /// The Products endpoint returns information about the Uber products
         /// offered at a given location. The response includes the display
         /// name and other details about each product, and lists the products
         /// in the proper display order.
+        /// </remarks>
         /// <param name='animalCreateOrUpdateParameter'>
         /// An Animal
         /// </param>

AutoRest/Generators/CSharp/CSharp.Tests/Expected/Mirror.Polymorphic/PolymorphicAnimalStore.cs

@@ -156,10 +156,12 @@ private void Initialize()
         /// <summary>
         /// Product Types
         /// </summary>
+        /// <remarks>
         /// The Products endpoint returns information about the Uber products offered
         /// at a given location. The response includes the display name and other
         /// details about each product, and lists the products in the proper display
         /// order.
+        /// </remarks>
         /// <param name='animalCreateOrUpdateParameter'>
         /// An Animal
         /// </param>

AutoRest/Generators/CSharp/CSharp.Tests/Expected/Mirror.Polymorphic/PolymorphicAnimalStoreExtensions.cs

@@ -24,10 +24,12 @@ public static partial class PolymorphicAnimalStoreExtensions
             /// <summary>
             /// Product Types
             /// </summary>
+            /// <remarks>
             /// The Products endpoint returns information about the Uber products offered
             /// at a given location. The response includes the display name and other
             /// details about each product, and lists the products in the proper display
             /// order.
+            /// </remarks>
             /// <param name='operations'>
             /// The operations group for this extension method.
             /// </param>
@@ -42,10 +44,12 @@ public static Animal CreateOrUpdatePolymorphicAnimals(this IPolymorphicAnimalSto
             /// <summary>
             /// Product Types
             /// </summary>
+            /// <remarks>
             /// The Products endpoint returns information about the Uber products offered
             /// at a given location. The response includes the display name and other
             /// details about each product, and lists the products in the proper display
             /// order.
+            /// </remarks>
             /// <param name='operations'>
             /// The operations group for this extension method.
             /// </param>

AutoRest/Generators/CSharp/CSharp.Tests/Expected/Mirror.RecursiveTypes/IRecursiveTypesAPI.cs

@@ -41,10 +41,12 @@ public partial interface IRecursiveTypesAPI : IDisposable
             /// <summary>
         /// Products
         /// </summary>
+        /// <remarks>
         /// The Products endpoint returns information about the Uber products
         /// offered at a given location. The response includes the display
         /// name and other details about each product, and lists the products
         /// in the proper display order.
+        /// </remarks>
         /// <param name='subscriptionId'>
         /// Subscription Id.
         /// </param>

AutoRest/Generators/CSharp/CSharp.Tests/Expected/Mirror.RecursiveTypes/RecursiveTypesAPI.cs

@@ -154,10 +154,12 @@ private void Initialize()
         /// <summary>
         /// Products
         /// </summary>
+        /// <remarks>
         /// The Products endpoint returns information about the Uber products offered
         /// at a given location. The response includes the display name and other
         /// details about each product, and lists the products in the proper display
         /// order.
+        /// </remarks>
         /// <param name='subscriptionId'>
         /// Subscription Id.
         /// </param>

AutoRest/Generators/CSharp/CSharp.Tests/Expected/Mirror.RecursiveTypes/RecursiveTypesAPIExtensions.cs

@@ -24,10 +24,12 @@ public static partial class RecursiveTypesAPIExtensions
             /// <summary>
             /// Products
             /// </summary>
+            /// <remarks>
             /// The Products endpoint returns information about the Uber products offered
             /// at a given location. The response includes the display name and other
             /// details about each product, and lists the products in the proper display
             /// order.
+            /// </remarks>
             /// <param name='operations'>
             /// The operations group for this extension method.
             /// </param>
@@ -51,10 +53,12 @@ public static Product Post(this IRecursiveTypesAPI operations, string subscripti
             /// <summary>
             /// Products
             /// </summary>
+            /// <remarks>
             /// The Products endpoint returns information about the Uber products offered
             /// at a given location. The response includes the display name and other
             /// details about each product, and lists the products in the proper display
             /// order.
+            /// </remarks>
             /// <param name='operations'>
             /// The operations group for this extension method.
             /// </param>

AutoRest/Generators/CSharp/CSharp.Tests/Expected/PetstoreV2/ISwaggerPetstoreV2.cs

@@ -79,7 +79,9 @@ public partial interface ISwaggerPetstoreV2 : IDisposable
         /// <summary>
         /// Finds Pets by status
         /// </summary>
+        /// <remarks>
         /// Multiple status values can be provided with comma seperated strings
+        /// </remarks>
         /// <param name='status'>
         /// Status values that need to be considered for filter
         /// </param>
@@ -94,8 +96,10 @@ public partial interface ISwaggerPetstoreV2 : IDisposable
         /// <summary>
         /// Finds Pets by tags
         /// </summary>
+        /// <remarks>
         /// Muliple tags can be provided with comma seperated strings. Use
         /// tag1, tag2, tag3 for testing.
+        /// </remarks>
         /// <param name='tags'>
         /// Tags to filter by
         /// </param>
@@ -110,7 +114,9 @@ public partial interface ISwaggerPetstoreV2 : IDisposable
         /// <summary>
         /// Find pet by Id
         /// </summary>
+        /// <remarks>
         /// Returns a single pet
+        /// </remarks>
         /// <param name='petId'>
         /// Id of pet to return
         /// </param>
@@ -164,7 +170,9 @@ public partial interface ISwaggerPetstoreV2 : IDisposable
         /// <summary>
         /// Returns pet inventories by status
         /// </summary>
+        /// <remarks>
         /// Returns a map of status codes to quantities
+        /// </remarks>
         /// <param name='customHeaders'>
         /// The headers that will be added to request.
         /// </param>
@@ -190,8 +198,10 @@ public partial interface ISwaggerPetstoreV2 : IDisposable
         /// <summary>
         /// Find purchase order by Id
         /// </summary>
+        /// <remarks>
         /// For valid response try integer IDs with value &lt;= 5 or &gt; 10.
         /// Other values will generated exceptions
+        /// </remarks>
         /// <param name='orderId'>
         /// Id of pet that needs to be fetched
         /// </param>
@@ -206,8 +216,10 @@ public partial interface ISwaggerPetstoreV2 : IDisposable
         /// <summary>
         /// Delete purchase order by Id
         /// </summary>
+        /// <remarks>
         /// For valid response try integer IDs with value &lt; 1000. Anything
         /// above 1000 or nonintegers will generate API errors
+        /// </remarks>
         /// <param name='orderId'>
         /// Id of the order that needs to be deleted
         /// </param>
@@ -222,7 +234,9 @@ public partial interface ISwaggerPetstoreV2 : IDisposable
         /// <summary>
         /// Create user
         /// </summary>
+        /// <remarks>
         /// This can only be done by the logged in user.
+        /// </remarks>
         /// <param name='body'>
         /// Created user object
         /// </param>
@@ -307,7 +321,9 @@ public partial interface ISwaggerPetstoreV2 : IDisposable
         /// <summary>
         /// Updated user
         /// </summary>
+        /// <remarks>
         /// This can only be done by the logged in user.
+        /// </remarks>
         /// <param name='username'>
         /// name that need to be deleted
         /// </param>
@@ -325,7 +341,9 @@ public partial interface ISwaggerPetstoreV2 : IDisposable
         /// <summary>
         /// Delete user
         /// </summary>
+        /// <remarks>
         /// This can only be done by the logged in user.
+        /// </remarks>
         /// <param name='username'>
         /// The name that needs to be deleted
         /// </param>