Add comprehensive Rider-specific troubleshooting guide for XML docs

Co-authored-by: omegaleo <5655201+omegaleo@users.noreply.github.com>
2026-02-11 23:22:09 +00:00
parent 374035e756
commit 9a00554faa
1 changed files with 266 additions and 0 deletions
@@ -0,0 +1,266 @@
+# 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:
+
+```bash
+# 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:
+
+```bash
+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:
+```bash
+# 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:
+
+```bash
+grep -A 5 "GetChangelogMarkdown" bin/Debug/net*/OmegaLeo.HelperLib.Changelog.xml
+```
+
+Should show:
+```xml
+<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:**
+```xml
+<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):**
+```xml
+<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:**
+```xml
+<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:
+
+```csharp
+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:**
+   ```bash
+   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!