Skip to content

Commit

Permalink
(C#) Adding support for "see" URLs in documentation (Azure#1167)
Browse files Browse the repository at this point in the history 
* Regenerating expected C# generated code and samples

* Adding ExternalDocsUrl to ClientModel

* Adding support for generating "see" tags in C# and Azure C# summary comments

* Adding externalDocs to some Swaggers and regenerating expected files

* Appeasing FxCop by suppressing a few rules and refactoring OperationBuilder
  • Loading branch information
@brjohnstmsft @fearthecowboy
brjohnstmsft authored and fearthecowboy committed Jun 15, 2016
1 parent 45a4711 commit ac312fe
Show file tree
Hide file tree
Showing 27 changed files with 239 additions and 48 deletions.
8 changes: 8 additions & 0 deletions AutoRest/AutoRest.Core/ClientModel/CompositeType.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
// Licensed under the MIT License. See License.txt in the project root for license information.

using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;
using System.Linq;

namespace Microsoft.Rest.Generator.ClientModel
Expand Down Expand Up @@ -61,6 +62,13 @@ public IEnumerable<Property> ComposedProperties
/// </summary>
public string Documentation { get; set; }

/// <summary>
/// Gets or sets a URL pointing to related external documentation.
/// </summary>
[SuppressMessage("Microsoft.Design", "CA1056:UriPropertiesShouldNotBeStrings",
Justification = "May not parse as a valid URI.")]
public string ExternalDocsUrl { get; set; }

/// <summary>
/// Returns true if any of the properties is a Constant or is
/// a CompositeType which ContainsConstantProperties set to true.
Expand Down
10 changes: 9 additions & 1 deletion AutoRest/AutoRest.Core/ClientModel/Method.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@

using System;
using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;
using System.Globalization;
using System.Linq;
using System.Net;
Expand Down Expand Up @@ -46,7 +47,7 @@ public Method()
/// <summary>
/// Gets or sets the HTTP url.
/// </summary>
[System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1056:UriPropertiesShouldNotBeStrings",
[SuppressMessage("Microsoft.Design", "CA1056:UriPropertiesShouldNotBeStrings",
Justification= "Url might be used as a template, thus making it invalid url in certain scenarios.")]
public string Url { get; set; }

Expand Down Expand Up @@ -135,6 +136,13 @@ public Parameter Body
/// </summary>
public string Summary { get; set; }

/// <summary>
/// Gets or sets a URL pointing to related external documentation.
/// </summary>
[SuppressMessage("Microsoft.Design", "CA1056:UriPropertiesShouldNotBeStrings",
Justification = "May not parse as a valid URI.")]
public string ExternalDocsUrl { get; set; }

/// <summary>
/// Gets or sets the content type.
/// </summary>
Expand Down
5 changes: 5 additions & 0 deletions ...rp.Tests/Expected/AcceptanceTests/AzureBodyDurationAllSync/AutoRestDurationTestService.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,10 @@ public AutoRestDurationTestService(Uri baseUri, ServiceClientCredentials credent
}
}

/// <summary>
/// An optional partial-method to perform custom initialization.
/// </summary>
partial void CustomInitialize();
/// <summary>
/// Initializes client properties.
/// </summary>
Expand Down Expand Up @@ -299,6 +303,7 @@ private void Initialize()
new Iso8601TimeSpanConverter()
}
};
CustomInitialize();
DeserializationSettings.Converters.Add(new CloudErrorJsonConverter());
}
}
Expand Down
5 changes: 5 additions & 0 deletions ...arp.Tests/Expected/AcceptanceTests/AzureBodyDurationNoSync/AutoRestDurationTestService.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,10 @@ public AutoRestDurationTestService(Uri baseUri, ServiceClientCredentials credent
}
}

/// <summary>
/// An optional partial-method to perform custom initialization.
/// </summary>
partial void CustomInitialize();
/// <summary>
/// Initializes client properties.
/// </summary>
Expand Down Expand Up @@ -299,6 +303,7 @@ private void Initialize()
new Iso8601TimeSpanConverter()
}
};
CustomInitialize();
DeserializationSettings.Converters.Add(new CloudErrorJsonConverter());
}
}
Expand Down
6 changes: 6 additions & 0 deletions ...arp.Tests/Expected/AcceptanceTests/AzureResource/AutoRestResourceFlatteningTestService.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -304,6 +304,7 @@ private void Initialize()
}
/// <summary>
/// Put External Resource as an Array
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='resourceArray'>
/// External Resource as an Array to put
Expand Down Expand Up @@ -445,6 +446,7 @@ private void Initialize()

/// <summary>
/// Get External Resource as an Array
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='customHeaders'>
/// Headers that will be added to request.
Expand Down Expand Up @@ -597,6 +599,7 @@ private void Initialize()

/// <summary>
/// Put External Resource as a Dictionary
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='resourceDictionary'>
/// External Resource as a Dictionary to put
Expand Down Expand Up @@ -738,6 +741,7 @@ private void Initialize()

/// <summary>
/// Get External Resource as a Dictionary
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='customHeaders'>
/// Headers that will be added to request.
Expand Down Expand Up @@ -890,6 +894,7 @@ private void Initialize()

/// <summary>
/// Put External Resource as a ResourceCollection
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='resourceComplexObject'>
/// External Resource as a ResourceCollection to put
Expand Down Expand Up @@ -1031,6 +1036,7 @@ private void Initialize()

/// <summary>
/// Get External Resource as a ResourceCollection
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='customHeaders'>
/// Headers that will be added to request.
Expand Down
12 changes: 12 additions & 0 deletions ...Expected/AcceptanceTests/AzureResource/AutoRestResourceFlatteningTestServiceExtensions.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ public static partial class AutoRestResourceFlatteningTestServiceExtensions
{
/// <summary>
/// Put External Resource as an Array
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand All @@ -38,6 +39,7 @@ public static partial class AutoRestResourceFlatteningTestServiceExtensions

/// <summary>
/// Put External Resource as an Array
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand All @@ -55,6 +57,7 @@ public static partial class AutoRestResourceFlatteningTestServiceExtensions

/// <summary>
/// Get External Resource as an Array
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand All @@ -66,6 +69,7 @@ public static IList<FlattenedProduct> GetArray(this IAutoRestResourceFlatteningT

/// <summary>
/// Get External Resource as an Array
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand All @@ -83,6 +87,7 @@ public static IList<FlattenedProduct> GetArray(this IAutoRestResourceFlatteningT

/// <summary>
/// Put External Resource as a Dictionary
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand All @@ -97,6 +102,7 @@ public static IList<FlattenedProduct> GetArray(this IAutoRestResourceFlatteningT

/// <summary>
/// Put External Resource as a Dictionary
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand All @@ -114,6 +120,7 @@ public static IList<FlattenedProduct> GetArray(this IAutoRestResourceFlatteningT

/// <summary>
/// Get External Resource as a Dictionary
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand All @@ -125,6 +132,7 @@ public static IDictionary<string, FlattenedProduct> GetDictionary(this IAutoRest

/// <summary>
/// Get External Resource as a Dictionary
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand All @@ -142,6 +150,7 @@ public static IDictionary<string, FlattenedProduct> GetDictionary(this IAutoRest

/// <summary>
/// Put External Resource as a ResourceCollection
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand All @@ -156,6 +165,7 @@ public static IDictionary<string, FlattenedProduct> GetDictionary(this IAutoRest

/// <summary>
/// Put External Resource as a ResourceCollection
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand All @@ -173,6 +183,7 @@ public static IDictionary<string, FlattenedProduct> GetDictionary(this IAutoRest

/// <summary>
/// Get External Resource as a ResourceCollection
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand All @@ -184,6 +195,7 @@ public static ResourceCollection GetResourceCollection(this IAutoRestResourceFla

/// <summary>
/// Get External Resource as a ResourceCollection
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
Expand Down
4 changes: 4 additions & 0 deletions ...ators/CSharp/Azure.CSharp.Tests/Expected/AcceptanceTests/AzureResource/Models/Resource.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ namespace Fixtures.Azure.AcceptanceTestsAzureResource.Models
using Microsoft.Rest.Serialization;
using Microsoft.Rest.Azure;

/// <summary>
/// Some resource
/// <see href="http://tempuri.org" />
/// </summary>
public partial class Resource : IResource
{
/// <summary>
Expand Down
8 changes: 8 additions & 0 deletions AutoRest/Generators/CSharp/Azure.CSharp/Templates/AzureMethodTemplate.cshtml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ if (!string.IsNullOrWhiteSpace(Model.Description) || !string.IsNullOrWhiteSpace(
{
@:/// <summary>
@:@WrapComment("/// ", String.IsNullOrEmpty(Model.Summary) ? Model.Description.EscapeXmlComment() : Model.Summary.EscapeXmlComment())
if (!string.IsNullOrWhiteSpace(Model.ExternalDocsUrl))
{
@:/// <see href="@Model.ExternalDocsUrl" />
}
@:/// </summary>
}
if (!String.IsNullOrEmpty(Model.Description) && !String.IsNullOrEmpty(Model.Summary))
Expand Down Expand Up @@ -53,6 +57,10 @@ if (!String.IsNullOrEmpty(Model.Description) || !String.IsNullOrEmpty(Model.Summ
{
@:/// <summary>
@:@WrapComment("/// ", String.IsNullOrEmpty(Model.Summary) ? Model.Description.EscapeXmlComment() : Model.Summary.EscapeXmlComment())
if (!string.IsNullOrWhiteSpace(Model.ExternalDocsUrl))
{
@:/// <see href="@Model.ExternalDocsUrl" />
}
@:/// </summary>
}
if (!String.IsNullOrEmpty(Model.Description) && !String.IsNullOrEmpty(Model.Summary))
Expand Down
9 changes: 9 additions & 0 deletions ...p.Tests/Expected/AcceptanceTests/ModelFlattening/AutoRestResourceFlatteningTestService.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,7 @@ private void Initialize()
}
/// <summary>
/// Put External Resource as an Array
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='resourceArray'>
/// External Resource as an Array to put
Expand Down Expand Up @@ -269,6 +270,7 @@ private void Initialize()

/// <summary>
/// Get External Resource as an Array
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='customHeaders'>
/// Headers that will be added to request.
Expand Down Expand Up @@ -394,6 +396,7 @@ private void Initialize()

/// <summary>
/// Put External Resource as a Dictionary
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='resourceDictionary'>
/// External Resource as a Dictionary to put
Expand Down Expand Up @@ -508,6 +511,7 @@ private void Initialize()

/// <summary>
/// Get External Resource as a Dictionary
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='customHeaders'>
/// Headers that will be added to request.
Expand Down Expand Up @@ -633,6 +637,7 @@ private void Initialize()

/// <summary>
/// Put External Resource as a ResourceCollection
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='resourceComplexObject'>
/// External Resource as a ResourceCollection to put
Expand Down Expand Up @@ -747,6 +752,7 @@ private void Initialize()

/// <summary>
/// Get External Resource as a ResourceCollection
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='customHeaders'>
/// Headers that will be added to request.
Expand Down Expand Up @@ -872,6 +878,7 @@ private void Initialize()

/// <summary>
/// Put Simple Product with client flattening true on the model
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='simpleBodyProduct'>
/// Simple body product to put
Expand Down Expand Up @@ -1011,6 +1018,7 @@ private void Initialize()

/// <summary>
/// Put Flattened Simple Product with client flattening true on the parameter
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='productId'>
/// Unique identifier representing a specific product for a given latitude
Expand Down Expand Up @@ -1181,6 +1189,7 @@ private void Initialize()

/// <summary>
/// Put Simple Product with client flattening true on the model
/// <see href="http://tempuri.org" />
/// </summary>
/// <param name='flattenParameterGroup'>
/// Additional parameters for the operation
Expand Down
Loading

0 comments on commit ac312fe

Please sign in to comment.