omegaleo/HelperLib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 19 Wiki Activity

Fix XML documentation generation to appear in IDE tooltips + recommend markdown

Browse Source 
Co-authored-by: omegaleo <5655201+omegaleo@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-02-11 23:07:32 +00:00
parent 22c5c4bfd3
commit f5b0e3209e
4 changed files with 61 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
OmegaLeo.HelperLib.XmlDocGenerator/EXAMPLE.md
+22
View File
@@ -1,5 +1,27 @@
# Documentation Attribute IDE Tooltip Example
## Recommended: Use Markdown for Code Examples
For the best IDE experience, we **strongly recommend using markdown code fences** in your `codeExample` parameter:
```csharp
[Documentation(
"MyMethod",
"Does something cool",
new[] { "param: Description" },
@"```csharp
// Use markdown code fences like this!
MyMethod(""example"");
```"
)]
```
This provides:
- ✅ Proper syntax highlighting in IDEs
- ✅ Better formatting in IntelliSense tooltips
- ✅ Consistent appearance across Visual Studio, Rider, and VS Code
- ✅ Markdown rendering in documentation generators
## Before (Without XML Doc Generator)
When using the `DocumentationAttribute` without the XML Doc Generator, IDEs would not show the documentation:
OmegaLeo.HelperLib.XmlDocGenerator/README.md
+27 -2
View File
@@ -22,12 +22,37 @@ If you want to use the XmlDocGenerator standalone:
dotnet add package OmegaLeo.HelperLib.XmlDocGenerator
```
## Usage Best Practices
### ✨ Recommended: Use Markdown in Code Examples
For the best IDE experience, **use markdown code fences** in your `codeExample` parameter:
```csharp
[Documentation(
"MyMethod",
"Does something cool",
new[] { "param: Description" },
@"```csharp
// Markdown code fence provides syntax highlighting!
MyMethod(""example"");
```"
)]
public void MyMethod(string param) { }
```
**Benefits:**
- ✅ Proper syntax highlighting in Visual Studio, Rider, and VS Code
- ✅ Better formatting in IntelliSense tooltips
- ✅ Professional appearance
- ✅ Works with documentation generators
## How It Works
1. **MSBuild Integration**: The package includes MSBuild targets that are automatically imported
2. **Build-Time Generation**: Runs after CoreCompile to analyze your compiled assembly
2. **Build-Time Generation**: Runs after Build to augment your final XML documentation
3. **Attribute Reading**: Uses reflection to read DocumentationAttribute instances
4. **XML Generation**: Creates/augments XML documentation files
4. **XML Generation**: Creates/augments XML documentation files in your output directory
5. **IntelliSense Ready**: IDEs automatically pick up the generated XML
## Features
OmegaLeo.HelperLib.XmlDocGenerator/build/OmegaLeo.HelperLib.XmlDocGenerator.targets
+4 -3
View File
@@ -2,14 +2,15 @@
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="GenerateXmlDocFromDocumentationAttribute"
AfterTargets="CoreCompile"
AfterTargets="Build"
Condition="'$(GenerateXmlDocFromDocumentationAttribute)' == 'true' And '$(TargetFramework)' != ''">
<PropertyGroup>
<!-- Path to the XmlDocGenerator tool in the NuGet package -->
<XmlDocGenToolPath>$(MSBuildThisFileDirectory)..\tools\net8.0\OmegaLeo.HelperLib.XmlDocGenerator.dll</XmlDocGenToolPath>
<TargetAssemblyPath>$(IntermediateOutputPath)$(TargetFileName)</TargetAssemblyPath>
<TargetXmlDocPath>$(IntermediateOutputPath)$(TargetName).xml</TargetXmlDocPath>
<!-- Target the final output assembly and XML, not intermediate -->
<TargetAssemblyPath>$(TargetDir)$(TargetFileName)</TargetAssemblyPath>
<TargetXmlDocPath>$(TargetDir)$(TargetName).xml</TargetXmlDocPath>
</PropertyGroup>
<Message Text="[DocumentationAttribute] Generating XML documentation from DocumentationAttribute for $(TargetName)"
XmlDocGeneratorLocal.props
+8 -3
View File
@@ -12,14 +12,15 @@
</PropertyGroup>
<Target Name="GenerateXmlDocFromDocumentationAttribute_Local"
AfterTargets="CoreCompile"
AfterTargets="Build"
Condition="'$(GenerateXmlDocFromDocumentationAttribute)' == 'true' And '$(TargetFramework)' != ''">
<PropertyGroup>
<!-- For local development, use the built tool from the sibling project -->
<XmlDocGenToolPath_Local>$(MSBuildThisFileDirectory)OmegaLeo.HelperLib.XmlDocGenerator/bin/$(Configuration)/net8.0/OmegaLeo.HelperLib.XmlDocGenerator.dll</XmlDocGenToolPath_Local>
<TargetAssemblyPath>$(IntermediateOutputPath)$(TargetFileName)</TargetAssemblyPath>
<TargetXmlDocPath>$(IntermediateOutputPath)$(TargetName).xml</TargetXmlDocPath>
<!-- Target the final output assembly and XML, not intermediate -->
<TargetAssemblyPath>$(TargetDir)$(TargetFileName)</TargetAssemblyPath>
<TargetXmlDocPath>$(TargetDir)$(TargetName).xml</TargetXmlDocPath>
</PropertyGroup>
<Message Text="[DocumentationAttribute] Generating XML documentation from DocumentationAttribute for $(TargetName)"
@@ -30,6 +31,10 @@
Importance="high"
Condition="!Exists('$(XmlDocGenToolPath_Local)')" />
<Message Text="[DocumentationAttribute] Target assembly not found at: $(TargetAssemblyPath)"
Importance="high"
Condition="!Exists('$(TargetAssemblyPath)')" />
<!-- Run the XmlDocGenerator tool -->
<Exec Command="dotnet &quot;$(XmlDocGenToolPath_Local)&quot; &quot;$(TargetAssemblyPath)&quot; &quot;$(TargetXmlDocPath)&quot;"
Condition="Exists('$(XmlDocGenToolPath_Local)') And Exists('$(TargetAssemblyPath)')"