-
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
Conversation
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.
This is awesome!
@@ -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 comment
The 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 comment
The 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 comment
The reason will be displayed to describe this comment to others. Learn more.
Sorry, my question was more about whether a custom snippet
attribute on the <code>
element would cause any problems with the doc generation tools. It shouldn't, but I've found previous generations of doc generation tools like Sandcastle to be very finicky. Might be worth an extra doc generation test after we merge it as a sanity check between releases.
}); | ||
} | ||
|
||
var originalText = File.ReadAllText(file); |
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?)
FYI @scbedd looks like the .NET snippet processor is also adding support for snippets in doc comments. |
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.
This is cool!!!
No description provided.