Use XML File as Comment Repository

Hello, 

Thanks for contacting Rider support. 

Getting comments from external XML file is supported in Rider. Please refer to the sample below to achieve what you need:

    /// <include file='xml_include_tag.xml' path='MyDocs/MyMembers[@name="test"]/param' />
    public void Execute(object sender)
    {
        throw new NotImplementedException();
    }

xml file:

<?xml version="1.0" encoding="utf-8"?>
<MyDocs>
    <MyMembers name="test">
        <summary>
            The summary for this type.
        </summary>
        <param name="sender">my sender argument to the method</param>
    </MyMembers>
</MyDocs>

Let me know if it doesn't work for you. 

Resource:

Documentation comments - C# language specification | Microsoft Learn

Regards,

Tom

I tried reproducing your example, but I got “Unable to include XML fragment: The system cannot find the file specified”.

I placed the xml file directly in the project directory. Could this be the problem?

It works for me to place the xmlfile in project folder. I've uploaded my entire project in https://github.com/laika1234/XMLCommentTest 

Please take a look and see if there is any clue. If not, could you share a sample project that can reproduce the issue? You can upload it to our Upload Service and let me know the Upload ID.

Thanks,

Tom

I figured out the problem! My code file was interpreting the <include file='GlobalComments.xml' as being in the same folder it was in. However, it was in a deeper folder, while GlobalComments.xml was in a higher one. I fixed it by putting <include file='../../GlobalComments.xml'.

Unfortunately, I have other problems now. (Don't computers just love doing that?) Based on the example you gave me, I was able to get comments to appear for my parameters in the method summary. However, when I hovered over the parameter names, their comments didn't appear.

I did find a solution that fixes that problem, but it comes with its own glitch. It looks like this:

/// <summary>
/// Detects when the user tries to reset the program.
/// </summary>
/// <param name="sender">
/// <include file='GlobalComments.xml' path='comments/variables/object[@name="sender"]' />
/// </param>
/// <param name="e">
/// <include file='GlobalComments.xml' path='comments/variables/EventArgs[@name="e"]' />
/// </param>
void OnReset(object sender, EventArgs e)
{
    Thread.Sleep(1000);
}
<?xml version="1.0" encoding="utf-8"?>
<comments>
    <variables>
        <EventArgs name="e">
            Indicates what object was the actual source of the event.
        </EventArgs>
        <object name="sender">
            What transmitted the event to listeners.
        </object>
    </variables>
</comments>

When I hovered over the method summary and parameter names, the parameters comments appeared like this:

<object name="sender"> What transmitted the event to listeners. </object>

<EventArgs name="e"> Indicates what object was the actual source of the event. </EventArgs>

As you can see, some of the XML markup is leaking over to the comments, even though I just want the plain text within that markup. Is there any way for me to fix this?

Happy to hear from you. The way you're doing is not recommended. I would suggest you use the recommended tag name as mentioned in Documentation comments - C# language specification | Microsoft Learn. 

For parameters, you can use param tag as demonstrated in my sample:
<param name="sender">my sender argument to the method</param>

Then change path of <include> to use wildcard (*), thus you don't need to specify xml section manually for every member and parameter will be recognzed correctly. 

Regards,

Tom

Thanks for your response.

So, your suggestion has three problems for me. The first is that the XML comment doesn't appear when you hover over the variable. I might be able to live with that, but the second problem is that this is very inflexible for my needs.

To explain in more detail, what I want is to share documentation for parameters that are repeated throughout my code. For example, object sender is often used in event handlers, but its functionality is always the same, so it would make sense for its documentation to be in one place. However, using your method, I would need to set up an XML comment for every method that uses object sender. That would result in duplicate documentation for object sender, which is exactly the situation I'm trying to avoid.

Now, you might say that I could just set up a comment for a dummy method and point object sender to that. However, that also doesn't work out very well, because object sender is almost never on its own. In my code, for example, it's paired with KeyEventArgs, PointerPressedEventArgs, RoutedEventArgs, etc. I would need to make a dummy method comment for each different combination, which again would duplicate documentation for object sender. (It also would be quite confusing.) That's why I set up my XML documentation the way I did, so I could avoid those issues.

The third problem is that sometimes I want to share documentation between a variable and a parameter. That isn't possible with your approach.

So, is there any way I can get my posted strategy to not leak XML markup? Would it be a good idea to submit a bug for this?

Thanks for the clarification. It's recommended to raise a new issue on our issue tracker, including the screenshot. The issue would be handled by a dedicated developer. 

Thanks,

Tom