Add XmlCommentGenerator example and documentation #429
Conversation
Added XmlCommentGenerator as the 240th Roslyn Source Code Generator example, including new sample project, documentation, and related metadata. Updated README, lists, and category files to reflect the new example and incremented counts. Also fixed a minor link replacement in MultiGeneratorV2.cs.
WalkthroughThis PR adds the 240th Roslyn Source Code Generator example (XmlCommentGenerator) to the collection. Changes include: adding the example project with source files, documentation pages, metadata entries in JSON data files, and updating link-normalization logic in the generator to rewrite documentation links from local to remote paths. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (12)
v2/rscg_examples/XmlCommentGenerator/readme.txt (1)
1-227: Consider replacing or annotating upstream VMR README for clarityThis readme appears to be a verbatim copy of the dotnet/dotnet VMR documentation, which may be confusing in the context of a focused XmlCommentGenerator example. Consider either:
- Replacing it with a short, sample-specific README (what the example does, how to run it), or
- Adding a brief note at the top explaining that the file is copied from the upstream repo for context, with a link back.
v2/rscg_examples/XmlCommentGenerator/description.json (1)
18-18: Minor: Empty string in includeAdditionalFiles array.The
includeAdditionalFilesfield contains an empty string[""]. If no additional files are needed, consider using an empty array[]instead for cleaner configuration.Apply this diff if no additional files are required:
- "includeAdditionalFiles":[""] + "includeAdditionalFiles":[]v2/book/examples/XmlCommentGenerator.html (4)
21-22: Fix mismatched NuGet link text.Anchor text says “XmlCommentGenerator” but links to Microsoft.AspNetCore.OpenApi. Align the text to the actual package name.
- Add reference to the <a href="https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi/" target="_blank">XmlCommentGenerator</a> in the csproj + Add reference to the <a href="https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi/" target="_blank" rel="noopener noreferrer">Microsoft.AspNetCore.OpenApi</a> in the csproj
5-5: Harden external links opened in new tabs.Add rel="noopener noreferrer" to anchors with target="_blank" to prevent tab‑napping.
-<a href="https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi/" target="_blank"> +<a href="https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi/" target="_blank" rel="noopener noreferrer"> -<a href="https://dotnet.microsoft.com/en-us/apps/aspnet" target="_blank"> +<a href="https://dotnet.microsoft.com/en-us/apps/aspnet" target="_blank" rel="noopener noreferrer"> -<a href="https://github.com/dotnet/dotnet/" target="_blank"> +<a href="https://github.com/dotnet/dotnet/" target="_blank" rel="noopener noreferrer"> -<a target="_blank" href='https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator'> +<a target="_blank" rel="noopener noreferrer" href='https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator'> -<a target="_blank" href='https://ignatandrei.github.io/RSCG_Examples/v2/docs/List-of-RSCG'> +<a target="_blank" rel="noopener noreferrer" href='https://ignatandrei.github.io/RSCG_Examples/v2/docs/List-of-RSCG'>Also applies to: 7-7, 11-11, 21-22, 41-43, 49-51
23-23: Add descriptive alt text for images (a11y).Images lack alt. Provide concise, meaningful alt attributes.
-<img src="images/XmlCommentGenerator/TestProgram.csproj.png" width="580" height="580" /> +<img src="images/XmlCommentGenerator/TestProgram.csproj.png" width="580" height="580" alt="Project file showing Microsoft.AspNetCore.OpenApi package reference" /> -<img src="images/XmlCommentGenerator/csFiles/Program.cs.png" width="580" height="580" /> +<img src="images/XmlCommentGenerator/csFiles/Program.cs.png" width="580" height="580" alt="Program.cs minimal API sample" /> -<img src="images/XmlCommentGenerator/generated/OpenApiXmlCommentSupport.generated.cs.png" width="580" height="580" /> +<img src="images/XmlCommentGenerator/generated/OpenApiXmlCommentSupport.generated.cs.png" width="580" height="580" alt="Generated OpenApiXmlCommentSupport code" />[ suggest_recommended_refactor ]
Also applies to: 30-30, 37-37
9-9: Minor copy edit.Normalize spacing after colon.
-<p>Author :Microsoft</p> +<p>Author: Microsoft</p>README.md (2)
38-51: Point “Source” to aspnetcore repo (more precise).The generator code is maintained in dotnet/aspnetcore. Suggest updating the “Source” link.
-Source: [https://github.com/dotnet/dotnet/](https://github.com/dotnet/dotnet/) +Source: [https://github.com/dotnet/aspnetcore](https://github.com/dotnet/aspnetcore)Please confirm this aligns with the commit/area you want to reference.
22-22: Fix markdownlint MD034 (bare URL).Format the bare URL as a proper markdown link.
-If you want to be notified each time I add a new RSCG example , please click https://dashboard.mailerlite.com/forms/611357/100178843411678256/share +If you want to be notified each time I add a new RSCG example, please click [this subscribe link](https://dashboard.mailerlite.com/forms/611357/100178843411678256/share).v2/rscg_examples_site/docs/RSCG-Examples/XmlCommentGenerator.md (4)
18-21: Use aspnetcore repo in badges for accuracy.Replace badges targeting dotnet/dotnet with dotnet/aspnetcore.
-[](https://github.com/dotnet/dotnet/) - +[](https://github.com/dotnet/aspnetcore) +Confirm this is the intended repository for the showcased generator.
48-49: Improve image alt text (a11y).Replace placeholder “Alt text” with a descriptive alt.
- +
1019-1024: Harden external share links.Add rel="noopener noreferrer" for links opened in new tabs.
-<a href="https://www.facebook.com/sharer/sharer.php?u=...XmlCommentGenerator" title="Share on Facebook" target="_blank">Share on Facebook</a> +<a href="https://www.facebook.com/sharer/sharer.php?u=...XmlCommentGenerator" title="Share on Facebook" target="_blank" rel="noopener noreferrer">Share on Facebook</a> -<a href="https://twitter.com/intent/tweet?source=...XmlCommentGenerator" target="_blank" title="Tweet">Share in Twitter</a> +<a href="https://twitter.com/intent/tweet?source=...XmlCommentGenerator" target="_blank" rel="noopener noreferrer" title="Tweet">Share on Twitter</a> -<a href="http://www.reddit.com/submit?url=...XmlCommentGenerator&title=XmlCommentGenerator" target="_blank" title="Submit to Reddit">Share on Reddit</a> +<a href="http://www.reddit.com/submit?url=...XmlCommentGenerator&title=XmlCommentGenerator" target="_blank" rel="noopener noreferrer" title="Submit to Reddit">Share on Reddit</a> -<a href="http://www.linkedin.com/shareArticle?mini=true&url=...XmlCommentGenerator" target="_blank" title="Share on LinkedIn">Share on Linkedin</a> +<a href="http://www.linkedin.com/shareArticle?mini=true&url=...XmlCommentGenerator" target="_blank" rel="noopener noreferrer" title="Share on LinkedIn">Share on Linkedin</a>
1026-1026: Fix bare URL rendering.Wrap the bare URL to satisfy markdown linters.
-https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator +<https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (3)
v2/Generator/all.csvis excluded by!**/*.csvv2/rscg_examples_site/static/exports/RSCG.xlsxis excluded by!**/*.xlsxv2/rscg_examples_site/static/sources/XmlCommentGenerator.zipis excluded by!**/*.zip
📒 Files selected for processing (27)
README.md(2 hunks)later.md(1 hunks)v2/.tours/XmlCommentGenerator.tour(1 hunks)v2/Generator/MultiGeneratorV2.cs(1 hunks)v2/RSCGExamplesData/GeneratorDataRec.json(1 hunks)v2/book/examples/XmlCommentGenerator.html(1 hunks)v2/book/list.html(2 hunks)v2/book/pandocHTML.yaml(1 hunks)v2/rscg_examples/XmlCommentGenerator/description.json(1 hunks)v2/rscg_examples/XmlCommentGenerator/nuget.txt(1 hunks)v2/rscg_examples/XmlCommentGenerator/readme.txt(1 hunks)v2/rscg_examples/XmlCommentGenerator/src/TestProgram.slnx(1 hunks)v2/rscg_examples/XmlCommentGenerator/src/TestProgram/Program.cs(1 hunks)v2/rscg_examples/XmlCommentGenerator/src/TestProgram/Properties/launchSettings.json(1 hunks)v2/rscg_examples/XmlCommentGenerator/src/TestProgram/TestProgram.csproj(1 hunks)v2/rscg_examples/XmlCommentGenerator/src/TestProgram/TestProgram.http(1 hunks)v2/rscg_examples/XmlCommentGenerator/src/TestProgram/appsettings.Development.json(1 hunks)v2/rscg_examples/XmlCommentGenerator/src/TestProgram/appsettings.json(1 hunks)v2/rscg_examples/XmlCommentGenerator/video.json(1 hunks)v2/rscg_examples_site/docs/Categories/API.md(2 hunks)v2/rscg_examples_site/docs/Categories/_PrimitiveAPI.mdx(1 hunks)v2/rscg_examples_site/docs/RSCG-Examples/XmlCommentGenerator.md(1 hunks)v2/rscg_examples_site/docs/RSCG-Examples/index.md(4 hunks)v2/rscg_examples_site/docs/about.md(1 hunks)v2/rscg_examples_site/docs/indexRSCG.md(4 hunks)v2/rscg_examples_site/src/components/HomepageFeatures/index.js(1 hunks)v2/rscg_examples_site/static/exports/RSCG.json(1 hunks)
🧰 Additional context used
🪛 Biome (2.1.2)
v2/rscg_examples/XmlCommentGenerator/video.json
[error] 35-36: Property key must be double quoted
(parse)
[error] 36-36: unexpected character =
(parse)
[error] 36-36: expected , but instead found " "
Remove " "
(parse)
[error] 36-36: expected : but instead found }
Remove }
(parse)
[error] 37-38: Expected an array, an object, or a literal but instead found ']'.
Expected an array, an object, or a literal here.
(parse)
🪛 LanguageTool
v2/rscg_examples_site/docs/Categories/_PrimitiveAPI.mdx
[style] ~23-~23: Using many exclamation marks might seem excessive (in this case: 22 exclamation marks for a text that’s 3463 characters long)
Context: ...packages/Microsoft.AspNetCore.OpenApi/) 
v2/rscg_examples/XmlCommentGenerator/readme.txt
[style] ~12-~12: This phrase is redundant. Consider using “inside”.
Context: ...h product repository which are mirrored inside of their respective directories under [`sr...
(OUTSIDE_OF)
[grammar] ~34-~34: Ensure spelling is correct
Context: ...rements of .NET distro builders such as RedHat or Canonical to natively include .NET i...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~39-~39: Use a hyphen to join words.
Context: ...s in its various existing repos. The day to day experience for typical contributo...
(QB_NEW_EN_HYPHEN)
[grammar] ~39-~39: Use a hyphen to join words.
Context: ...n its various existing repos. The day to day experience for typical contributors ...
(QB_NEW_EN_HYPHEN)
[grammar] ~66-~66: Use a hyphen to join words.
Context: ...ries, except VMR pipeline changes. - Non src/* directories - Directly in VMR - ...
(QB_NEW_EN_HYPHEN)
[grammar] ~68-~68: Ensure spelling is correct
Context: ...y. They should only be updated via a re-bootrap of the VMR. - A VMR build uses `src/a...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~109-~109: Use a hyphen to join words.
Context: ...ollowing build modes: - Microsoft based build For Unix: ...
(QB_NEW_EN_HYPHEN)
[style] ~196-~196: This phrase is redundant. Consider using “outside”.
Context: ...vide additional arguments when building outside of a context of a git repository. Altern...
(OUTSIDE_OF)
[style] ~203-~203: Consider a more expressive alternative.
Context: ...he VMR, commit, and then open a PR. To do this, you need to use the [`darc vmr fo...
(DO_ACHIEVE)
v2/rscg_examples_site/docs/RSCG-Examples/XmlCommentGenerator.md
[style] ~65-~65: This phrase is redundant. Consider using “inside”.
Context: ...h product repository which are mirrored inside of their respective directories under [`sr...
(OUTSIDE_OF)
[grammar] ~87-~87: Ensure spelling is correct
Context: ...rements of .NET distro builders such as RedHat or Canonical to natively include .NET i...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~92-~92: Use a hyphen to join words.
Context: ...s in its various existing repos. The day to day experience for typical contributo...
(QB_NEW_EN_HYPHEN)
[grammar] ~92-~92: Use a hyphen to join words.
Context: ...n its various existing repos. The day to day experience for typical contributors ...
(QB_NEW_EN_HYPHEN)
[grammar] ~119-~119: Use a hyphen to join words.
Context: ...ries, except VMR pipeline changes. - Non src/* directories - Directly in VMR - ...
(QB_NEW_EN_HYPHEN)
[grammar] ~121-~121: Ensure spelling is correct
Context: ...y. They should only be updated via a re-bootrap of the VMR. - A VMR build uses `src/a...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~162-~162: Use a hyphen to join words.
Context: ...ollowing build modes: - Microsoft based build For Unix: ...
(QB_NEW_EN_HYPHEN)
[style] ~249-~249: This phrase is redundant. Consider using “outside”.
Context: ...vide additional arguments when building outside of a context of a git repository. Altern...
(OUTSIDE_OF)
[style] ~256-~256: Consider a more expressive alternative.
Context: ...he VMR, commit, and then open a PR. To do this, you need to use the [`darc vmr fo...
(DO_ACHIEVE)
🪛 markdownlint-cli2 (0.18.1)
README.md
42-42: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Agent
- GitHub Check: CodeQL analysis (javascript-typescript)
- GitHub Check: CodeQL analysis (csharp)
- GitHub Check: call-workflow-passing-data / build (24.3.0)
🔇 Additional comments (31)
v2/book/pandocHTML.yaml (1)
256-256: LGTM!The new XmlCommentGenerator.html entry is correctly added to the input files list with proper YAML formatting.
v2/RSCGExamplesData/GeneratorDataRec.json (1)
1451-1456: LGTM!The XmlCommentGenerator entry is properly structured with all required fields and correct JSON syntax.
v2/rscg_examples/XmlCommentGenerator/nuget.txt (1)
1-3: LGTM!The package description clearly explains the functionality and includes proper source attribution.
later.md (1)
3-3: LGTM!The date update correctly reflects the addition of the new XmlCommentGenerator example.
v2/rscg_examples/XmlCommentGenerator/src/TestProgram/appsettings.Development.json (1)
1-8: LGTM!Standard ASP.NET Core development configuration with appropriate logging levels.
v2/rscg_examples/XmlCommentGenerator/src/TestProgram/appsettings.json (1)
1-9: LGTM!Standard ASP.NET Core configuration appropriate for a test/example project.
v2/Generator/MultiGeneratorV2.cs (1)
148-148: LGTM!The new link normalization follows the established pattern for converting relative documentation links to full source URLs.
v2/rscg_examples/XmlCommentGenerator/src/TestProgram/TestProgram.csproj (3)
14-17: LGTM!The EmitCompilerGeneratedFiles configuration is appropriate for an RSCG example project, allowing developers to inspect the generated code.
12-12: The package version 10.0.0 exists and is correct.The project targets .NET 10.0 (line 4:
<TargetFramework>net10.0</TargetFramework>), and Microsoft.AspNetCore.OpenApi version 10.0.0 is the latest stable version available on NuGet. The package version correctly aligns with the .NET framework version. No changes are needed.
4-4: Original review comment is incorrect.The project correctly targets
net10.0, which was officially released on November 11, 2025 as a Long-Term Support (LTS) version. As of November 2025, .NET 10.0 is the latest stable .NET release, not .NET 9.0. The suggested diff to downgrade tonet9.0would be incorrect and unnecessary.No changes are required.
v2/rscg_examples/XmlCommentGenerator/src/TestProgram.slnx (1)
1-3: Solution definition looks correctSingle project reference and relative path are consistent with the folder layout; no issues here.
v2/rscg_examples/XmlCommentGenerator/src/TestProgram/Properties/launchSettings.json (1)
1-15: Launch profile is consistent with the sample APIPort, launchUrl, and environment match the
/todosendpoints and HTTP file; this is fine as-is.v2/rscg_examples/XmlCommentGenerator/src/TestProgram/TestProgram.http (1)
1-11: HTTP requests align with the API surfaceThe host, paths, and headers are aligned with the
/todosendpoints and launch settings; useful for quick manual testing.v2/rscg_examples/XmlCommentGenerator/src/TestProgram/Program.cs (1)
1-48: Minimal API + JSON context wiring looks correct; verify target framework/languageThe Slim builder, typed
Results<Ok<Todo>, NotFound>endpoint,DateOnly, collection expressions ([...]), andJsonSerializerContextusage all look consistent with modern ASP.NET Core minimal API patterns and should work well for demonstrating the XmlCommentGenerator output.Just make sure that:
- The project targets a .NET / C# version that supports
WebApplication.CreateSlimBuilderand collection expressions, and- Implicit usings (or an explicit
using System.Linq;) are enabled soFirstOrDefaultresolves cleanly.v2/rscg_examples_site/docs/Categories/API.md (1)
3-25: New API category entry is consistentThe XmlCommentGenerator entry (item 11) matches the existing format (link, NuGet badge, stars, date), and the updated
Number RSCG: 11aligns with the list length.v2/book/list.html (1)
20-21: List count and new row 240 are alignedUpdating the heading to 240 and appending XmlCommentGenerator as row 240 keeps the table numbering and example count in sync with the rest of the catalog.
Also applies to: 985-988
v2/rscg_examples_site/src/components/HomepageFeatures/index.js (1)
7-7: LGTM! Consistent count update.The example count and Microsoft attribution are correctly updated to reflect the new XmlCommentGenerator addition.
v2/rscg_examples_site/docs/about.md (1)
9-9: LGTM! Documentation count updated correctly.The count is properly updated to reflect 240 total examples.
v2/rscg_examples_site/docs/Categories/_PrimitiveAPI.mdx (1)
23-24: LGTM! New API entry properly formatted.The XmlCommentGenerator entry is correctly added with proper badges, links, and date format consistent with other entries.
v2/rscg_examples_site/static/exports/RSCG.json (1)
1916-1924: LGTM! Valid JSON entry for XmlCommentGenerator.The new entry is properly structured with correct fields, valid JSON syntax, and appropriate metadata.
v2/rscg_examples/XmlCommentGenerator/description.json (1)
20-22: Empty blog and video links.The
blogandvideofields are currently empty. This is fine for initial submission, but consider adding documentation links if available.v2/rscg_examples_site/docs/indexRSCG.md (3)
10-12: LGTM! List heading and counts updated correctly.The page heading and summary are properly updated to reflect 240 total examples with 16 from Microsoft.
23-23: LGTM! New entry properly added to chronological list.XmlCommentGenerator is correctly positioned as item 240 with proper date format and category.
264-285: LGTM! Microsoft section updated consistently.The Microsoft-specific section correctly shows 16 items and includes the new XmlCommentGenerator entry.
v2/rscg_examples_site/docs/RSCG-Examples/index.md (4)
3-4: LGTM! Page metadata updated correctly.Title and description properly reflect 240 total examples.
52-52: LGTM! API category count updated.The summary correctly shows 11 examples in the API category.
103-107: LGTM! New API entry added with proper formatting.XmlCommentGenerator is correctly added to the API section with consistent Markdown structure.
1524-1524: LGTM! Mermaid diagram updated correctly.The new node and edge for XmlCommentGenerator are properly added to the flowchart with valid Mermaid syntax.
v2/book/examples/XmlCommentGenerator.html (1)
11-11: Confirm correct “Source” repository.Xml comment/OpenAPI generators live under dotnet/aspnetcore. If you intend to point to the code origin, consider linking to that repo (or the specific path) instead of dotnet/dotnet VMR.
Do you want to switch to https://github.com/dotnet/aspnetcore/ here?
v2/rscg_examples_site/docs/RSCG-Examples/XmlCommentGenerator.md (2)
10-10: Verify import path for SameCategory component.Importing ../Categories/_PrimitiveAPI.mdx looks unusual for an API example. Ensure the component exists and corresponds to the “API” category to prevent build-time MDX errors.
If it should be the API category component, should this be
_API.mdxinstead?
314-315: Package version sanity check.Pinned Version="10.0.0". Please confirm this version contains XmlCommentGenerator in Microsoft.AspNetCore.OpenApi.
If you want “floating latest within major”, consider:
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.*" />
| "steps": | ||
| [ | ||
| { | ||
| "file": "rscg_examples/XmlCommentGenerator/src/TestProgram/TestProgram.csproj", | ||
| "description": "First, we add Nuget [Microsoft.AspNetCore.OpenApi](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi/) in csproj ", | ||
| "pattern": "Microsoft.AspNetCore.OpenApi" | ||
| } | ||
|
|
||
| ,{ | ||
| "file": "rscg_examples/XmlCommentGenerator/src/TestProgram/Program.cs", | ||
| "description": "File Program.cs \r\n>> dotnet run --project rscg_examples/XmlCommentGenerator/src/TestProgram/TestProgram.csproj ", | ||
| "pattern": "this is the code" | ||
| } | ||
|
|
||
|
|
||
| ,{ | ||
| "file": "rscg_examples/XmlCommentGenerator/src/TestProgram/obj/GX/Microsoft.AspNetCore.OpenApi.SourceGenerators/Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator/OpenApiXmlCommentSupport.generated.cs", | ||
| "description": "Generated File 1 from 1 : OpenApiXmlCommentSupport.generated.cs ", | ||
| "line": 1 | ||
| } | ||
|
|
||
| ], | ||
|
|
||
| "ref": "main" | ||
|
|
||
| } No newline at end of file |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# List all .tour files to understand the structure
find . -name "*.tour" -type f | head -20Repository: ignatandrei/RSCG_Examples
Length of output: 1214
🏁 Script executed:
#!/bin/bash
# Check the specific Program.cs file mentioned
if [ -f "v2/rscg_examples/XmlCommentGenerator/src/TestProgram/Program.cs" ]; then
echo "=== File exists at v2/ path ==="
wc -l "v2/rscg_examples/XmlCommentGenerator/src/TestProgram/Program.cs"
cat -n "v2/rscg_examples/XmlCommentGenerator/src/TestProgram/Program.cs"
elif [ -f "rscg_examples/XmlCommentGenerator/src/TestProgram/Program.cs" ]; then
echo "=== File exists at rscg_examples/ path (no v2) ==="
wc -l "rscg_examples/XmlCommentGenerator/src/TestProgram/Program.cs"
cat -n "rscg_examples/XmlCommentGenerator/src/TestProgram/Program.cs"
else
echo "=== File not found at either path ==="
fiRepository: ignatandrei/RSCG_Examples
Length of output: 1856
🏁 Script executed:
#!/bin/bash
# Check another .tour file to see path convention
if [ -f "v2/.tours" ]; then
ls -la v2/.tours/ | head -10
echo ""
echo "=== Checking a sample .tour file for path convention ==="
find v2/.tours -name "*.tour" -type f | head -1 | xargs head -30
fiRepository: ignatandrei/RSCG_Examples
Length of output: 51
🏁 Script executed:
#!/bin/bash
# Read the XmlCommentGenerator.tour file
echo "=== XmlCommentGenerator.tour content ==="
cat v2/.tours/XmlCommentGenerator.tour
echo ""
echo "=== Program.tour (sample top-level tour) ==="
head -40 v2/.tours/Program.tour
echo ""
echo "=== TUnit.tour (another sample top-level tour) ==="
head -40 v2/.tours/TUnit.tourRepository: ignatandrei/RSCG_Examples
Length of output: 3958
🏁 Script executed:
#!/bin/bash
# Check a nested tour file for comparison
echo "=== Sample nested tour file for path convention ==="
head -40 v2/rscg_examples/ActorSrcGen/src/.tours/ActorSrcGen.tourRepository: ignatandrei/RSCG_Examples
Length of output: 1161
The pattern issue is systemic across all .tour files; path convention is correct
The review's concern about paths is incorrect. All top-level .tour files in v2/.tours/ consistently use rscg_examples/... without the v2/ prefix, which is the established convention across the entire repository. This path format is correct and matches Program.tour, TUnit.tour, and all other samples.
However, the pattern issue is valid but far broader than stated: The string "this is the code" appears as a placeholder pattern in virtually every second step across all .tour files in the repository (not just XmlCommentGenerator). This is a systemic issue, not specific to this file. All these tours use this placeholder, suggesting it's a template artifact rather than an intentional pattern.
Recommendation: The pattern should be replaced with an actual code snippet from the respective file (e.g., WebApplication.CreateSlimBuilder for XmlCommentGenerator.tour's Program.cs step, as originally suggested). This is part of a broader tour maintenance task affecting multiple files.
| {"typeStep":"browser","arg":"https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator#download-example-net--c-", | ||
| SpeakTest=" "}, |
There was a problem hiding this comment.
Critical JSON syntax error.
Lines 35-36 contain malformed JSON. The property assignment uses = instead of : and appears to be incorrectly structured.
Apply this diff to fix the JSON syntax:
-{"typeStep":"browser","arg":"https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator#download-example-net--c-",
-SpeakTest=" "},
+{"typeStep":"browser","arg":"https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator#download-example-net--c-"},If SpeakTest is intended as a property, it should be formatted as:
-{"typeStep":"browser","arg":"https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator#download-example-net--c-",
-SpeakTest=" "},
+{"typeStep":"browser","arg":"https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator#download-example-net--c-", "SpeakTest":" "},📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| {"typeStep":"browser","arg":"https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator#download-example-net--c-", | |
| SpeakTest=" "}, | |
| {"typeStep":"browser","arg":"https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator#download-example-net--c-"}, |
🧰 Tools
🪛 Biome (2.1.2)
[error] 35-36: Property key must be double quoted
(parse)
[error] 36-36: unexpected character =
(parse)
[error] 36-36: expected , but instead found " "
Remove " "
(parse)
[error] 36-36: expected : but instead found }
Remove }
(parse)
🤖 Prompt for AI Agents
In v2/rscg_examples/XmlCommentGenerator/video.json around lines 35-36, the JSON
entry uses `=` and incorrect structure; change the property assignment to use a
colon with a quoted key and value (e.g., "SpeakTest": " ") and ensure the object
entry follows JSON rules (proper commas between items and no trailing comma if
it is the last property).
There was a problem hiding this comment.
Pull request overview
This pull request adds XmlCommentGenerator as the 240th Roslyn Source Code Generator example to the repository, including comprehensive documentation, sample project files, and metadata updates across multiple systems.
Key changes:
- Added XmlCommentGenerator example with complete documentation and code samples
- Updated RSCG counts from 239 to 240 throughout the repository
- Updated Microsoft-created RSCG count from 15 to 16
- Added link replacement pattern for absolute paths in MultiGeneratorV2.cs
Reviewed changes
Copilot reviewed 28 out of 30 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| v2/rscg_examples_site/docs/RSCG-Examples/XmlCommentGenerator.md | New comprehensive documentation page for XmlCommentGenerator with code examples and usage instructions |
| v2/rscg_examples_site/static/sources/XmlCommentGenerator.zip | Binary archive containing the complete example project |
| v2/rscg_examples_site/static/exports/RSCG.xlsx | Updated Excel export with new entry for XmlCommentGenerator |
| v2/rscg_examples_site/static/exports/RSCG.json | Added XmlCommentGenerator metadata to JSON export |
| v2/rscg_examples_site/src/components/HomepageFeatures/index.js | Updated example counts on homepage (239→240, 15→16 from Microsoft) |
| v2/rscg_examples_site/docs/indexRSCG.md | Added XmlCommentGenerator to chronological list and Microsoft section |
| v2/rscg_examples_site/docs/about.md | Updated total RSCG count in about page |
| v2/rscg_examples_site/docs/RSCG-Examples/index.md | Added XmlCommentGenerator to API category and updated category count |
| v2/rscg_examples_site/docs/Categories/_PrimitiveAPI.mdx | Added XmlCommentGenerator entry to API category primitive list |
| v2/rscg_examples_site/docs/Categories/API.md | Added XmlCommentGenerator to API category page |
| v2/rscg_examples/XmlCommentGenerator/video.json | Video script configuration for XmlCommentGenerator example |
| v2/rscg_examples/XmlCommentGenerator/src/TestProgram/. | Complete ASP.NET Core Web API example project demonstrating XmlCommentGenerator |
| v2/rscg_examples/XmlCommentGenerator/readme.txt | README from dotnet/dotnet VMR repository |
| v2/rscg_examples/XmlCommentGenerator/nuget.txt | NuGet package description |
| v2/rscg_examples/XmlCommentGenerator/description.json | Generator metadata and configuration |
| v2/book/pandocHTML.yaml | Added XmlCommentGenerator to book generation input files |
| v2/book/list.html | Added XmlCommentGenerator entry to HTML list |
| v2/book/examples/XmlCommentGenerator.html | Generated HTML documentation page |
| v2/RSCGExamplesData/GeneratorDataRec.json | Added XmlCommentGenerator record with category and date metadata |
| v2/Generator/all.csv | Added XmlCommentGenerator entry to CSV catalog |
| v2/Generator/MultiGeneratorV2.cs | Fixed link replacement to handle absolute paths starting with /docs/ |
| v2/.tours/XmlCommentGenerator.tour | CodeTour configuration for guided walkthrough |
| later.md | Updated latest update date to 2025-11-09 |
| README.md | Updated counts and added XmlCommentGenerator entry to main README |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "excludeDirectoryGenerated":["Microsoft.AspNetCore.App.SourceGenerators", | ||
| "Microsoft.AspNetCore.Http.RequestDelegateGenerator", | ||
| "System.Text.Json.SourceGeneration"], |
There was a problem hiding this comment.
Incorrect indentation for array items. Lines 16-17 should be indented to align with line 15. The current indentation breaks the JSON structure and makes it inconsistent.
| "excludeDirectoryGenerated":["Microsoft.AspNetCore.App.SourceGenerators", | |
| "Microsoft.AspNetCore.Http.RequestDelegateGenerator", | |
| "System.Text.Json.SourceGeneration"], | |
| "excludeDirectoryGenerated":[ | |
| "Microsoft.AspNetCore.App.SourceGenerators", | |
| "Microsoft.AspNetCore.Http.RequestDelegateGenerator", | |
| "System.Text.Json.SourceGeneration" | |
| ], |
| ,{ | ||
| "file": "rscg_examples/XmlCommentGenerator/src/TestProgram/Program.cs", | ||
| "description": "File Program.cs \r\n>> dotnet run --project rscg_examples/XmlCommentGenerator/src/TestProgram/TestProgram.csproj ", | ||
| "pattern": "this is the code" |
There was a problem hiding this comment.
The pattern property value "this is the code" does not match any actual code in Program.cs. This pattern is used for CodeTour navigation and should match actual code text in the file, such as "using System.Text.Json.Serialization" or another distinctive line from the file.
| "pattern": "this is the code" | |
| "pattern": "using System;" |
| .WithName("GetTodos"); | ||
|
|
||
| todosApi.MapGet("/{id}", Results<Ok<Todo>, NotFound> (int id) => | ||
| sampleTodos.FirstOrDefault(a => a.Id == id) is \{ \} todo |
There was a problem hiding this comment.
The escaped curly braces \{ \} should be regular curly braces { } in the markdown documentation. This appears to be a rendering issue where the actual code in Program.cs uses { } but the documentation incorrectly shows \{ \}.
| sampleTodos.FirstOrDefault(a => a.Id == id) is \{ \} todo | |
| sampleTodos.FirstOrDefault(a => a.Id == id) is { } todo |
| {"typeStep":"waitseconds","arg":"30"}, | ||
| {"typeStep":"text","arg": "Remember, you can download the code from here"}, | ||
| {"typeStep":"browser","arg":"https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator#download-example-net--c-", | ||
| SpeakTest=" "}, |
There was a problem hiding this comment.
Missing comma after the SpeakTest property. This will cause a JSON syntax error. The line should end with a comma like SpeakTest=" "},.
| SpeakTest=" "}, | |
| "SpeakTest": " "}, |
| {"typeStep":"text","arg": "Remember, you can download the code from here"}, | ||
| {"typeStep":"browser","arg":"https://ignatandrei.github.io/RSCG_Examples/v2/docs/XmlCommentGenerator#download-example-net--c-", | ||
| SpeakTest=" "}, | ||
| {"typeStep":"waitseconds","arg":"30"}, |
There was a problem hiding this comment.
Trailing comma after the last array element is not valid JSON. Remove the comma after line 37 to avoid JSON parsing errors.
| {"typeStep":"waitseconds","arg":"30"}, | |
| {"typeStep":"waitseconds","arg":"30"} |
| if (methodComment.Summary is \{ \} summary) | ||
| { | ||
| operation.Summary = summary; | ||
| } | ||
| if (methodComment.Description is \{ \} description) | ||
| { | ||
| operation.Description = description; | ||
| } | ||
| if (methodComment.Remarks is \{ \} remarks) | ||
| { | ||
| operation.Description = remarks; | ||
| } | ||
| if (methodComment.Parameters is \{ Count: > 0}) | ||
| { | ||
| foreach (var parameterComment in methodComment.Parameters) | ||
| { | ||
| var parameterInfo = methodInfo.GetParameters().SingleOrDefault(info => info.Name == parameterComment.Name); | ||
| var operationParameter = operation.Parameters?.SingleOrDefault(parameter => parameter.Name == parameterComment.Name); | ||
| if (operationParameter is not null) | ||
| { | ||
| var targetOperationParameter = UnwrapOpenApiParameter(operationParameter); | ||
| targetOperationParameter.Description = parameterComment.Description; | ||
| if (parameterComment.Example is \{ \} jsonString) | ||
| { | ||
| targetOperationParameter.Example = jsonString.Parse(); | ||
| } | ||
| targetOperationParameter.Deprecated = parameterComment.Deprecated; | ||
| } | ||
| else | ||
| { | ||
| var requestBody = operation.RequestBody; | ||
| if (requestBody is not null) | ||
| { | ||
| requestBody.Description = parameterComment.Description; | ||
| if (parameterComment.Example is \{ \} jsonString) | ||
| { | ||
| var content = requestBody?.Content?.Values; | ||
| if (content is null) | ||
| { | ||
| continue; | ||
| } | ||
| foreach (var mediaType in content) | ||
| { | ||
| mediaType.Example = jsonString.Parse(); | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| // Applies `<returns>` on XML comments for operation with single response value. | ||
| if (methodComment.Returns is \{ \} returns && operation.Responses is \{ Count: 1 }) | ||
| { | ||
| var response = operation.Responses.First(); | ||
| response.Value.Description = returns; | ||
| } | ||
| // Applies `<response>` on XML comments for operation with multiple response values. | ||
| if (methodComment.Responses is \{ Count: > 0} && operation.Responses is \{ Count: > 0 }) | ||
| { | ||
| foreach (var response in operation.Responses) | ||
| { | ||
| var responseComment = methodComment.Responses.SingleOrDefault(xmlResponse => xmlResponse.Code == response.Key); | ||
| if (responseComment is not null) | ||
| { | ||
| response.Value.Description = responseComment.Description; | ||
| } | ||
| } | ||
| } | ||
| } | ||
| foreach (var parameterDescription in context.Description.ParameterDescriptions) | ||
| { | ||
| var metadata = parameterDescription.ModelMetadata; | ||
| if (metadata.MetadataKind == ModelMetadataKind.Property | ||
| && metadata.ContainerType is \{ \} containerType | ||
| && metadata.PropertyName is \{ \} propertyName) | ||
| { | ||
| var propertyDocId = DocumentationCommentIdHelper.CreateDocumentationId(containerType, propertyName); | ||
| if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyDocId), out var propertyComment)) | ||
| { | ||
| var parameter = operation.Parameters?.SingleOrDefault(p => p.Name == metadata.Name); | ||
| var description = propertyComment.Summary; | ||
| if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) | ||
| { | ||
| description = $"{description}\n{propertyComment.Value}"; | ||
| } | ||
| else if (string.IsNullOrEmpty(description)) | ||
| { | ||
| description = propertyComment.Value; | ||
| } | ||
| if (parameter is null) | ||
| { | ||
| if (operation.RequestBody is not null) | ||
| { | ||
| operation.RequestBody.Description = description; | ||
| if (propertyComment.Examples?.FirstOrDefault() is \{ \} jsonString) | ||
| { | ||
| var content = operation.RequestBody.Content?.Values; | ||
| if (content is null) | ||
| { | ||
| continue; | ||
| } | ||
| var parsedExample = jsonString.Parse(); | ||
| foreach (var mediaType in content) | ||
| { | ||
| mediaType.Example = parsedExample; | ||
| } | ||
| } | ||
| } | ||
| continue; | ||
| } | ||
| var targetOperationParameter = UnwrapOpenApiParameter(parameter); | ||
| if (targetOperationParameter is not null) | ||
| { | ||
| targetOperationParameter.Description = description; | ||
| if (propertyComment.Examples?.FirstOrDefault() is \{ \} jsonString) | ||
| { | ||
| targetOperationParameter.Example = jsonString.Parse(); | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
|
|
||
| return Task.CompletedTask; | ||
| } | ||
|
|
||
| private static OpenApiParameter UnwrapOpenApiParameter(IOpenApiParameter sourceParameter) | ||
| { | ||
| if (sourceParameter is OpenApiParameterReference parameterReference) | ||
| { | ||
| if (parameterReference.Target is OpenApiParameter target) | ||
| { | ||
| return target; | ||
| } | ||
| else | ||
| { | ||
| throw new InvalidOperationException($"The input schema must be an {nameof(OpenApiParameter)} or {nameof(OpenApiParameterReference)}."); | ||
| } | ||
| } | ||
| else if (sourceParameter is OpenApiParameter directParameter) | ||
| { | ||
| return directParameter; | ||
| } | ||
| else | ||
| { | ||
| throw new InvalidOperationException($"The input schema must be an {nameof(OpenApiParameter)} or {nameof(OpenApiParameterReference)}."); | ||
| } | ||
| } | ||
| } | ||
|
|
||
| [System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.AspNetCore.OpenApi.SourceGenerators, Version=10.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60", "10.0.0.0")] | ||
| file class XmlCommentSchemaTransformer : IOpenApiSchemaTransformer | ||
| { | ||
| public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken) | ||
| { | ||
| // Apply comments from the type | ||
| if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(context.JsonTypeInfo.Type.CreateDocumentationId()), out var typeComment)) | ||
| { | ||
| schema.Description = typeComment.Summary; | ||
| if (typeComment.Examples?.FirstOrDefault() is \{ \} jsonString) | ||
| { | ||
| schema.Example = jsonString.Parse(); | ||
| } | ||
| } | ||
|
|
||
| if (context.JsonPropertyInfo is \{ AttributeProvider: PropertyInfo propertyInfo }) | ||
| { | ||
| // Apply comments from the property | ||
| if (XmlCommentCache.Cache.TryGetValue(DocumentationCommentIdHelper.NormalizeDocId(propertyInfo.CreateDocumentationId()), out var propertyComment)) | ||
| { | ||
| var description = propertyComment.Summary; | ||
| if (!string.IsNullOrEmpty(description) && !string.IsNullOrEmpty(propertyComment.Value)) | ||
| { | ||
| description = $"{description}\n{propertyComment.Value}"; | ||
| } | ||
| else if (string.IsNullOrEmpty(description)) | ||
| { | ||
| description = propertyComment.Value; | ||
| } | ||
| if (schema.Metadata is null | ||
| || !schema.Metadata.TryGetValue("x-schema-id", out var schemaId) | ||
| || string.IsNullOrEmpty(schemaId as string)) | ||
| { | ||
| // Inlined schema | ||
| schema.Description = description; | ||
| if (propertyComment.Examples?.FirstOrDefault() is \{ \} jsonString) | ||
| { | ||
| schema.Example = jsonString.Parse(); | ||
| } | ||
| } | ||
| else | ||
| { | ||
| // Schema Reference | ||
| if (!string.IsNullOrEmpty(description)) | ||
| { | ||
| schema.Metadata["x-ref-description"] = description; | ||
| } | ||
| if (propertyComment.Examples?.FirstOrDefault() is \{ \} jsonString) | ||
| { | ||
| schema.Metadata["x-ref-example"] = jsonString.Parse()!; | ||
| } |
There was a problem hiding this comment.
The escaped curly braces \{ \} should be regular curly braces { } in the markdown documentation. This pattern matching syntax is incorrectly escaped throughout the generated code section. The actual generated code uses { } for pattern matching, not \{ \}.
Added XmlCommentGenerator as the 240th Roslyn Source Code Generator example, including new sample project, documentation, and related metadata. Updated README, lists, and category files to reflect the new example and incremented counts. Also fixed a minor link replacement in MultiGeneratorV2.cs.
Summary by CodeRabbit
Release Notes
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.