dotnet-api-docs icon indicating copy to clipboard operation
dotnet-api-docs copied to clipboard

Convert snippet references from old [!code-lang[...]] syntax to new :::code syntax

Open Copilot opened this issue 4 months ago • 2 comments

This PR converts all snippet references in XML documentation files from the legacy [!code-lang[...]] syntax to the new :::code syntax as specified in the issue requirements.

Changes Made

Before:

[!code-csharp[CreateElement Example](~/snippets/csharp/System.Xml/XmlDocument/CreateElement/source.cs#1)]
[!code-vb[System.Web.Profile.ProfileManager.ProfileAutoSaving#11](~/snippets/visualbasic/VS_Snippets_WebNet/System.Web.Profile.ProfileManager.ProfileAutoSaving/VB/global.asax#11)]
[!code-cpp[DiscoveryClientProtocol_AdditionalInformation#1](~/snippets/cpp/VS_Snippets_Remoting/DiscoveryClientProtocol_AdditionalInformation/CPP/discoveryclientprotocol_additionalinformation.cpp#1)]

After:

:::code language="csharp" source="~/snippets/csharp/System.Xml/XmlDocument/CreateElement/source.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Web.Profile.ProfileManager.ProfileAutoSaving/VB/global.asax" id="Snippet11":::
:::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/DiscoveryClientProtocol_AdditionalInformation/CPP/discoveryclientprotocol_additionalinformation.cpp" id="Snippet1":::

Transformation Rules Applied

  1. Language mapping: code-csharplanguage="csharp", code-vblanguage="vb", code-cpplanguage="cpp"
  2. Path extraction: Moved from (~/path/file.ext#id) to source="~/path/file.ext"
  3. ID normalization: Added "Snippet" prefix when missing (e.g., #1id="Snippet1")
  4. Description removal: Discarded description text as it's not used in the new format
  5. Syntax change: [!code-...]:::code ... :::

Summary

  • Files changed: 170 XML documentation files
  • Total conversions: ~1,742 snippet references converted
  • Languages supported: C#, VB.NET, and C++
  • Verification: All old-style references successfully converted with zero remaining [!code- patterns

This change modernizes the documentation to use the current standard snippet reference syntax while maintaining all existing functionality and snippet links.


💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

Copilot avatar Sep 03 '25 00:09 Copilot