-
Notifications
You must be signed in to change notification settings - Fork 4.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add XML Doc snippet support #11808
Add XML Doc snippet support #11808
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,49 @@ | ||
// Copyright (c) Microsoft Corporation. All rights reserved. | ||
// Licensed under the MIT License. | ||
|
||
using System; | ||
using System.Linq; | ||
using System.Security; | ||
using System.Text; | ||
using System.Text.RegularExpressions; | ||
|
||
namespace SnippetGenerator | ||
{ | ||
public class CSharpProcessor | ||
{ | ||
private static readonly string _snippetFormat = "{3} <code snippet=\"{0}\">{1}{2} </code>"; | ||
private static readonly Regex _snippetRegex = new Regex("^(?<indent>\\s*)\\/{3}\\s*<code snippet=\\\"(?<name>[\\w:]+)\\\">.*?\\/{3}\\s*<\\/code>", | ||
RegexOptions.Compiled | RegexOptions.Multiline | RegexOptions.Singleline | RegexOptions.IgnoreCase); | ||
|
||
public static string Process(string markdown, Func<string, string> snippetProvider) | ||
{ | ||
return _snippetRegex.Replace(markdown, match => | ||
{ | ||
var name = match.Groups["name"].Value; | ||
var prefix = match.Groups["indent"].Value + "///"; | ||
|
||
var snippetText = snippetProvider(name); | ||
|
||
var builder = new StringBuilder(); | ||
foreach (var line in snippetText.Split(Environment.NewLine)) | ||
{ | ||
builder.Append(prefix); | ||
if (!string.IsNullOrWhiteSpace(line)) | ||
{ | ||
builder.Append(" "); | ||
} | ||
|
||
builder.AppendLine(SecurityElement.Escape(line)); | ||
} | ||
|
||
if (builder.Length > 0) | ||
{ | ||
builder.Length -= Environment.NewLine.Length; | ||
} | ||
|
||
return string.Format(_snippetFormat, name, Environment.NewLine, builder, prefix); | ||
}); | ||
} | ||
|
||
} | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,4 @@ | ||
// Copyright (c) Microsoft Corporation. All rights reserved. | ||
// Copyright (c) Microsoft Corporation. All rights reserved. | ||
// Licensed under the MIT License. | ||
|
||
using System.Collections.Generic; | ||
|
@@ -13,6 +13,37 @@ namespace Azure | |
/// iterate over. | ||
/// </summary> | ||
/// <typeparam name="T">The type of the values.</typeparam> | ||
/// <example> | ||
/// Example of enumerating an AsyncPageable using the <c> async foreach </c> loop: | ||
/// <code snippet="Snippet:AsyncPageable"> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Any idea what will happen if we run this through our ref doc generation tools? Might want to hold off on merging this until we're through with the release so @scbedd and @chidozieononiwu don't have any fun surprises. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I expect something like this https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.hosting.windowsservices.webhostwindowsserviceextensions.runasservice?view=aspnetcore-3.0#examples I'll hold of this PR until the release cycle is done. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Sorry, my question was more about whether a custom |
||
/// // call a service method, which returns AsyncPageable<T> | ||
/// AsyncPageable<SecretProperties> allSecretProperties = client.GetPropertiesOfSecretsAsync(); | ||
/// | ||
/// await foreach (SecretProperties secretProperties in allSecretProperties) | ||
/// { | ||
/// Console.WriteLine(secretProperties.Name); | ||
/// } | ||
/// </code> | ||
/// or using a while loop: | ||
/// <code snippet="Snippet:AsyncPageableLoop"> | ||
/// // call a service method, which returns AsyncPageable<T> | ||
/// AsyncPageable<SecretProperties> allSecretProperties = client.GetPropertiesOfSecretsAsync(); | ||
/// | ||
/// IAsyncEnumerator<SecretProperties> enumerator = allSecretProperties.GetAsyncEnumerator(); | ||
/// try | ||
/// { | ||
/// while (await enumerator.MoveNextAsync()) | ||
/// { | ||
/// SecretProperties secretProperties = enumerator.Current; | ||
/// Console.WriteLine(secretProperties.Name); | ||
/// } | ||
/// } | ||
/// finally | ||
/// { | ||
/// await enumerator.DisposeAsync(); | ||
/// } | ||
/// </code> | ||
/// </example> | ||
public abstract class AsyncPageable<T> : IAsyncEnumerable<T> where T : notnull | ||
{ | ||
/// <summary> | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We're going to dramatically increase the number of files that get scanned. I wonder if it'd be more efficient to do it line by line? Not something to fix now, but might be worth filing a tracking bug for. (Doing a couple of perf measurements and speeding this up might make a good Tech Talk for the team?)