HelperLib/RIDER_XML_DOCS_TROUBLESHOOTING.md

Rider-Specific: Troubleshooting XML Documentation Display

The Problem

You're consuming OmegaLeo.HelperLib in your project (e.g., in HomeController.cs) and when hovering over methods like GetChangelogMarkdown or BenchmarkUtility.Start, you only see:

[Documentation("GetChangelogMarkdown", "Generates...", null, "")]
public static string GetChangelogMarkdown(IEnumerable<Assembly> assemblies)
 in class OmegaLeo.HelperLib.Changelog.Helpers.ChangelogHelper

Instead of the rich XML documentation.

Why This Happens in Rider

Rider has several caching mechanisms that can prevent it from picking up XML documentation files, especially after they've been regenerated or updated.

Verification: Are XML Files Present?

First, verify the XML files exist and have content:

# Check if XML files exist next to the DLLs
ls -la bin/Debug/net*/OmegaLeo.HelperLib*.xml

# Check content of Changelog XML
cat bin/Debug/net*/OmegaLeo.HelperLib.Changelog.xml

You should see files like:

• OmegaLeo.HelperLib.xml
• OmegaLeo.HelperLib.Changelog.xml
• OmegaLeo.HelperLib.Game.xml

Each should contain <member> tags with <summary> elements.

Solution Steps for Rider

Step 1: Invalidate Caches (Most Common Fix)

1. In Rider: File → Invalidate Caches...
2. Check all boxes:
   • ✅ Clear file system cache and Local History
   • ✅ Clear VCS Log caches and indexes
   • ✅ Clear downloaded shared indexes
   • ✅ Clear workspace model
   • ✅ Clean NuGet cache
3. Click Invalidate and Restart

Step 2: Clean and Rebuild

After Rider restarts:

dotnet clean
dotnet build --configuration Debug

Or in Rider:

1. Build → Clean Solution
2. Build → Rebuild All

Step 3: Check XML File Location

Rider needs the XML file to be in the same directory as the DLL:

bin/Debug/net8.0/
  ├── OmegaLeo.HelperLib.Changelog.dll  ← Must be here
  └── OmegaLeo.HelperLib.Changelog.xml  ← And here

Verify:

# Should show both .dll and .xml
ls -1 bin/Debug/net*/OmegaLeo.HelperLib.Changelog.*

Step 4: Verify XML Content

Check the XML actually has the documentation:

grep -A 5 "GetChangelogMarkdown" bin/Debug/net*/OmegaLeo.HelperLib.Changelog.xml

Should show:

<member name="M:OmegaLeo.HelperLib.Changelog.Helpers.ChangelogHelper.GetChangelogMarkdown...">
    <summary>Generates a markdown formatted changelog from the changelog attributes in the provided assemblies.</summary>
</member>

Step 5: Force Rider to Reload References

1. Right-click on your project in Solution Explorer
2. Properties
3. Go to Build → Output
4. Note the output path
5. Check that path has both .dll and .xml files

Or try:

1. Remove the reference to OmegaLeo.HelperLib.Changelog
2. Rebuild
3. Re-add the reference
4. Rebuild

Step 6: Check Quick Documentation Window

Instead of hover tooltip, try:

1. Place cursor on GetChangelogMarkdown
2. Press Ctrl+Q (Windows/Linux) or F1 (macOS)
3. This opens the Quick Documentation window
4. It should show the full documentation

Step 7: Verify Reference Type

Check how you're referencing the library:

If using ProjectReference:

<ProjectReference Include="..\HelperLib\OmegaLeo.HelperLib.Changelog\OmegaLeo.HelperLib.Changelog.csproj" />

Rider might prioritize source code over XML. Consider using a built DLL reference or PackageReference instead.

If using PackageReference (NuGet):

<PackageReference Include="OmegaLeo.HelperLib.Changelog" Version="1.2.1.1" />

Ensure the package includes the .xml files in the lib/ folder.

If using DLL Reference:

<Reference Include="OmegaLeo.HelperLib.Changelog">
  <HintPath>path\to\OmegaLeo.HelperLib.Changelog.dll</HintPath>
</Reference>

Ensure the .xml file is in the same directory as the .dll.

Advanced: Rider's External Annotations Cache

If the above doesn't work, Rider might have cached old annotations:

Windows:

%LOCALAPPDATA%\JetBrains\Rider<version>\resharper-host\local\Transient\ReSharperHost\

macOS:

~/Library/Caches/JetBrains/Rider<version>/resharper-host/local/Transient/ReSharperHost/

Linux:

~/.cache/JetBrains/Rider<version>/resharper-host/local/Transient/ReSharperHost/

Try deleting these caches while Rider is closed.

Testing the XML Documentation

Create a simple test:

using OmegaLeo.HelperLib.Changelog.Helpers;
using System.Reflection;

class Program
{
    static void Main()
    {
        // Hover over GetChangelogMarkdown - should show docs
        var markdown = ChangelogHelper.GetChangelogMarkdown(
            new[] { Assembly.GetExecutingAssembly() }
        );
    }
}

Build and open in Rider. If hover still doesn't work:

1. Try Ctrl+Q (Quick Documentation)
2. Check Find Usages → see if it shows documentation

Still Not Working?

Check Rider Settings

1. File → Settings → Editor → General → Code Completion
2. Ensure Show the documentation popup in (ms): is not 0
3. Try increasing to 500-1000ms

Check ReSharper Settings

1. File → Settings → Tools → ReSharper
2. External Sources → Enable XML Documentation comments
3. Ensure it's enabled

Last Resort: Complete Reset

1. Close Rider
2. Delete .idea folder in your solution directory
3. Delete Rider cache:
   • Windows: %LOCALAPPDATA%\JetBrains\Rider<version>\
   • macOS: ~/Library/Caches/JetBrains/Rider<version>/
   • Linux: ~/.cache/JetBrains/Rider<version>/
4. Reopen solution in Rider
5. Let it reindex everything

Expected Result

After following these steps, hovering over GetChangelogMarkdown should show:

GetChangelogMarkdown(IEnumerable<Assembly> assemblies): string

Generates a markdown formatted changelog from the changelog 
attributes in the provided assemblies.

Returns: The generated markdown string

Comparison: What You See vs. What You Should See

What You're Seeing (Wrong):

[Documentation("GetChangelogMarkdown", "Generates...", null, "")]
public static string GetChangelogMarkdown(IEnumerable<Assembly> assemblies)

What You Should See (Correct):

GetChangelogMarkdown(IEnumerable<Assembly> assemblies): string

Generates a markdown formatted changelog from the changelog 
attributes in the provided assemblies.

If All Else Fails

The issue might be with how the library is being referenced. Try:

1. Create a fresh test project:

   dotnet new console -n TestRider
   cd TestRider
   dotnet add reference path/to/OmegaLeo.HelperLib.Changelog.csproj
   dotnet build
   

2. Open ONLY this test project in Rider

3. Test if documentation appears

If documentation works in the test project but not in your main project, the issue is with your main project's configuration or Rider's cache for that specific solution.

Summary

The XML documentation IS being generated correctly. Rider-specific caching and reference resolution can prevent it from being displayed. The most common fix is:

1. Invalidate Caches and Restart
2. Clean and Rebuild
3. Ensure .xml files are next to .dll files

These steps should resolve the issue in 99% of cases!