WIP: Generate XML documentation from DocumentationAttribute for IDE IntelliSense #12

2026-02-11T22:15:17Z

Copilot commented

2026-02-11 22:15:17 +00:00

(Migrated from github.com)

Custom attributes don't render in IDE tooltips. The DocumentationAttribute contains rich metadata (description, parameters, examples) but IDEs show only the raw attribute syntax since they require XML documentation files.

Implementation

XmlDocGenerator MSBuild Package

Roslyn-based post-build tool extracts DocumentationAttribute from compiled assemblies
Augments XML documentation with <summary>, <remarks>, <example> elements
Packaged as MSBuild SDK with automatic target integration
Runs AfterTargets="Build" to process final output assemblies

Integration Points

XmlDocGeneratorLocal.props - Local development (path resolution for net9.0 runtime)
build/*.targets - NuGet consumer integration via MSBuild extensibility
OmegaLeo.HelperLib.Documentation package dependency - transitive installation

Test Infrastructure

42 unit tests covering MathExtensions, IListExtensions, BenchmarkUtility, NeoDictionary
xUnit framework integration
CI workflow already configured for automatic PR validation

XML Generation Example

// Source code (clean, attribute only)
[Documentation("Start", "Starts or restarts the stopwatch for the given key.")]
public static void Start(string key)

// Generated XML (IDE consumes this)
<member name="M:OmegaLeo.HelperLib.Helpers.BenchmarkUtility.Start(System.String)">
    <summary>Starts or restarts the stopwatch for the given key.</summary>
</member>

Configuration Updates

Added <GenerateDocumentationFile>true</GenerateDocumentationFile> to Changelog and Game projects (missing baseline XML generation)
Fixed tool path resolution from net8.0 to net9.0 (matches runtime)
Updated $(IntermediateOutputPath) to $(TargetDir) (IDEs read from bin, not obj)

Behavior

Library developers (ProjectReference): IDEs show source code, attributes visible in context
Package consumers (DLL reference): IDEs read XML files, rich IntelliSense from DocumentationAttribute

Works with Visual Studio, Rider, VS Code. Zero configuration for consumers - MSBuild targets auto-import from NuGet package cache.

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Custom attributes don't render in IDE tooltips. The `DocumentationAttribute` contains rich metadata (description, parameters, examples) but IDEs show only the raw attribute syntax since they require XML documentation files. ## Implementation **XmlDocGenerator MSBuild Package** - Roslyn-based post-build tool extracts `DocumentationAttribute` from compiled assemblies - Augments XML documentation with `<summary>`, `<remarks>`, `<example>` elements - Packaged as MSBuild SDK with automatic target integration - Runs `AfterTargets="Build"` to process final output assemblies **Integration Points** - `XmlDocGeneratorLocal.props` - Local development (path resolution for net9.0 runtime) - `build/*.targets` - NuGet consumer integration via MSBuild extensibility - `OmegaLeo.HelperLib.Documentation` package dependency - transitive installation **Test Infrastructure** - 42 unit tests covering MathExtensions, IListExtensions, BenchmarkUtility, NeoDictionary - xUnit framework integration - CI workflow already configured for automatic PR validation ## XML Generation Example ```csharp // Source code (clean, attribute only) [Documentation("Start", "Starts or restarts the stopwatch for the given key.")] public static void Start(string key) // Generated XML (IDE consumes this) <member name="M:OmegaLeo.HelperLib.Helpers.BenchmarkUtility.Start(System.String)"> <summary>Starts or restarts the stopwatch for the given key.</summary> </member> ``` ## Configuration Updates - Added `<GenerateDocumentationFile>true</GenerateDocumentationFile>` to Changelog and Game projects (missing baseline XML generation) - Fixed tool path resolution from net8.0 to net9.0 (matches runtime) - Updated `$(IntermediateOutputPath)` to `$(TargetDir)` (IDEs read from bin, not obj) ## Behavior **Library developers** (ProjectReference): IDEs show source code, attributes visible in context **Package consumers** (DLL reference): IDEs read XML files, rich IntelliSense from DocumentationAttribute Works with Visual Studio, Rider, VS Code. Zero configuration for consumers - MSBuild targets auto-import from NuGet package cache.  --- 💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).

omegaleo (Migrated from github.com) reviewed 2026-02-11 22:15:17 +00:00

Pull request closed

This pull request cannot be reopened because the branch was deleted.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: omegaleo/HelperLib#12