Update XmlDocGenerator README with NuGet package usage
Co-authored-by: omegaleo <5655201+omegaleo@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
@@ -1,139 +1,54 @@
|
|||||||
# OmegaLeo.HelperLib.XmlDocGenerator
|
# OmegaLeo.HelperLib.XmlDocGenerator
|
||||||
|
|
||||||
A tool that automatically generates XML documentation from `DocumentationAttribute` custom attributes, making them visible in IDE tooltips.
|
Automatic XML documentation generator for DocumentationAttribute. This MSBuild package automatically generates XML documentation comments from your `DocumentationAttribute` declarations, making them visible in IDE IntelliSense and tooltips.
|
||||||
|
|
||||||
## What Problem Does This Solve?
|
## Installation
|
||||||
|
|
||||||
The `DocumentationAttribute` is a custom attribute that allows you to document classes, methods, and properties with rich information including descriptions, parameters, and code examples. However, custom attributes don't automatically appear in IDE hover tooltips.
|
### Automatic (Recommended)
|
||||||
|
|
||||||
This tool solves that problem by:
|
Simply install the OmegaLeo.HelperLib.Documentation package:
|
||||||
1. Reading the compiled assemblies after build
|
|
||||||
2. Extracting information from `DocumentationAttribute` instances
|
```bash
|
||||||
3. Generating/augmenting the XML documentation file with this information
|
dotnet add package OmegaLeo.HelperLib.Documentation
|
||||||
4. Making the documentation visible in IDEs like Visual Studio and JetBrains Rider
|
```
|
||||||
|
|
||||||
|
The XmlDocGenerator is automatically included as a dependency and will work out of the box!
|
||||||
|
|
||||||
|
### Manual
|
||||||
|
|
||||||
|
If you want to use the XmlDocGenerator standalone:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dotnet add package OmegaLeo.HelperLib.XmlDocGenerator
|
||||||
|
```
|
||||||
|
|
||||||
## How It Works
|
## How It Works
|
||||||
|
|
||||||
The tool is automatically run as a post-build step in projects that include the MSBuild target. It:
|
1. **MSBuild Integration**: The package includes MSBuild targets that are automatically imported
|
||||||
|
2. **Build-Time Generation**: Runs after CoreCompile to analyze your compiled assembly
|
||||||
|
3. **Attribute Reading**: Uses reflection to read DocumentationAttribute instances
|
||||||
|
4. **XML Generation**: Creates/augments XML documentation files
|
||||||
|
5. **IntelliSense Ready**: IDEs automatically pick up the generated XML
|
||||||
|
|
||||||
1. **Loads the assembly** with proper dependency resolution
|
## Features
|
||||||
2. **Finds all types** with `DocumentationAttribute`
|
|
||||||
3. **Extracts documentation** information (Title, Description, Args, CodeExample)
|
|
||||||
4. **Generates XML** in the standard .NET XML documentation format:
|
|
||||||
- `<summary>` - from Description
|
|
||||||
- `<remarks>` - from Args (parameters)
|
|
||||||
- `<example>` - from CodeExample
|
|
||||||
|
|
||||||
## Usage
|
- ✅ **Automatic**: Zero configuration needed
|
||||||
|
- ✅ **Build-time**: No runtime overhead
|
||||||
### In Your Code
|
- ✅ **Non-breaking**: Works alongside existing XML comments
|
||||||
|
- ✅ **Cross-platform**: Works on Windows, Linux, macOS
|
||||||
Use the `DocumentationAttribute` as usual:
|
- ✅ **Multi-targeting**: Supports all .NET target frameworks
|
||||||
|
- ✅ **IDE Support**: Works with Visual Studio, Rider, VS Code
|
||||||
```csharp
|
|
||||||
[Documentation(
|
|
||||||
"MyMethod",
|
|
||||||
"This method does something important.",
|
|
||||||
new string[] { "param1: The first parameter.", "param2: The second parameter." },
|
|
||||||
@"```csharp
|
|
||||||
MyMethod(param1, param2);
|
|
||||||
```"
|
|
||||||
)]
|
|
||||||
public void MyMethod(string param1, int param2)
|
|
||||||
{
|
|
||||||
// Method implementation
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Build Integration
|
|
||||||
|
|
||||||
The tool is automatically integrated into the build process for projects that include the MSBuild target. No manual action is required.
|
|
||||||
|
|
||||||
When you build your project, you'll see a message like:
|
|
||||||
```
|
|
||||||
[DocumentationAttribute] Augmenting XML documentation for YourProject from DocumentationAttribute
|
|
||||||
```
|
|
||||||
|
|
||||||
### Viewing in IDE
|
|
||||||
|
|
||||||
Once built, hover over any method, class, or property with a `DocumentationAttribute` in your IDE:
|
|
||||||
|
|
||||||
- **Visual Studio**: Hover tooltip will show the documentation
|
|
||||||
- **JetBrains Rider**: Quick Documentation (Ctrl+Q / F1) will show the documentation
|
|
||||||
- **VS Code**: IntelliSense will show the documentation
|
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
The tool runs automatically after the Build target with these settings:
|
By default, XML generation is enabled. To disable it:
|
||||||
|
|
||||||
```xml
|
```xml
|
||||||
<Target Name="GenerateXmlDocFromAttributes" AfterTargets="Build">
|
<PropertyGroup>
|
||||||
<PropertyGroup>
|
<GenerateXmlDocFromDocumentationAttribute>false</GenerateXmlDocFromDocumentationAttribute>
|
||||||
<XmlDocGenExe>$(MSBuildThisFileDirectory)../OmegaLeo.HelperLib.XmlDocGenerator/bin/$(Configuration)/net8.0/OmegaLeo.HelperLib.XmlDocGenerator.dll</XmlDocGenExe>
|
</PropertyGroup>
|
||||||
<TargetAssembly>$(TargetDir)$(TargetFileName)</TargetAssembly>
|
|
||||||
<TargetXmlDoc>$(TargetDir)$(TargetName).xml</TargetXmlDoc>
|
|
||||||
</PropertyGroup>
|
|
||||||
|
|
||||||
<Exec Command="dotnet "$(XmlDocGenExe)" "$(TargetAssembly)" "$(TargetXmlDoc)""
|
|
||||||
Condition="Exists('$(XmlDocGenExe)') And Exists('$(TargetAssembly)')"
|
|
||||||
IgnoreExitCode="true"
|
|
||||||
ContinueOnError="true" />
|
|
||||||
</Target>
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Requirements
|
## License
|
||||||
|
|
||||||
- .NET 8.0 SDK (for building the tool)
|
AGPL-3.0-only
|
||||||
- Projects must have `GenerateDocumentationFile` enabled (optional but recommended for best results)
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
### Tool not running
|
|
||||||
- Ensure the XmlDocGenerator project is built first: `dotnet build OmegaLeo.HelperLib.XmlDocGenerator/OmegaLeo.HelperLib.XmlDocGenerator.csproj`
|
|
||||||
- Check that the path in the MSBuild target is correct relative to your project
|
|
||||||
|
|
||||||
### Documentation not showing in IDE
|
|
||||||
- Ensure the XML file is generated in the output directory
|
|
||||||
- For consumed packages, ensure the XML file is included in the package
|
|
||||||
- Restart your IDE if it doesn't pick up changes
|
|
||||||
|
|
||||||
### Assembly loading errors
|
|
||||||
- The tool uses `AssemblyLoadContext` to load assemblies and their dependencies
|
|
||||||
- Dependencies must be present in the same directory as the target assembly
|
|
||||||
|
|
||||||
## Examples
|
|
||||||
|
|
||||||
### Before (Custom Attribute Only)
|
|
||||||
```csharp
|
|
||||||
[Documentation("Calculate", "Calculates something", new[] { "x: First number", "y: Second number" })]
|
|
||||||
public int Calculate(int x, int y) => x + y;
|
|
||||||
```
|
|
||||||
|
|
||||||
**IDE shows**: No documentation (custom attributes don't appear in tooltips)
|
|
||||||
|
|
||||||
### After (With XML Doc Generator)
|
|
||||||
The same code now generates:
|
|
||||||
```xml
|
|
||||||
<member name="M:MyNamespace.MyClass.Calculate(System.Int32,System.Int32)">
|
|
||||||
<summary>Calculates something</summary>
|
|
||||||
<remarks>
|
|
||||||
Parameters:
|
|
||||||
- x: First number
|
|
||||||
- y: Second number
|
|
||||||
</remarks>
|
|
||||||
</member>
|
|
||||||
```
|
|
||||||
|
|
||||||
**IDE shows**: Full documentation with description and parameter information!
|
|
||||||
|
|
||||||
## Technical Details
|
|
||||||
|
|
||||||
- **Language**: C# (.NET 8.0)
|
|
||||||
- **Dependencies**: `System.Reflection.Metadata`
|
|
||||||
- **XML Format**: Standard .NET XML documentation format
|
|
||||||
- **Assembly Loading**: Uses `AssemblyLoadContext` for isolated loading
|
|
||||||
- **Performance**: Runs only during build, no runtime overhead
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
To modify the XML generation logic, see `Program.cs` in the XmlDocGenerator project.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user