Add XML Doc snippet support #11808
Add XML Doc snippet support #11808
Conversation
pakrym
requested review from
chidozieononiwu,
danieljurek,
KrzysztofCwalina,
mitchdenny and
weshaggard
as code owners
| @@ -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.
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.
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.
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.
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. |
No description provided.