XML documentation of Action parameters in C#

Question

I am looking for a way to document action parameters in C#. Code looks like this:

/// <summary>
/// Do some action with parameters.
/// </summary>
/// <params name="someAction"> This is action but what about parameters? </param>
public void Do(Action<int,int,string> someAction)

How can I name and document parameters of "someAction" so that they would appear in intellisense?

You mean how to show it in intellisense with syntax highlighting? Or documentate the type parameters? — Furkan Kambay, Feb 09 '18 at 19:20
When I type in VS Do( then it autocompletes it with (i, i1, arg3) =>. I want names instead of i, i1 and arg3. — Optional Option, Feb 09 '18 at 19:21
@JonSkeet your comment made me think. I have no idea what you mean :) — Optional Option, Feb 09 '18 at 19:27
Just document it as "The action to perform. When called by this method, the first argument will be the index, the second will be the count, and the third will be the name" or whatever. The parameters of `Action` are just named `arg1`, `arg2` and `arg3`. — Jon Skeet, Feb 09 '18 at 19:28
So you are saying that what I want is not possible. And what is with Jon Skeet upvotes? Is this guy getting upvotes just for typing? This is weird. — Optional Option, Feb 09 '18 at 19:35
You can use separate delegate for that. So instead of Action - use custom delegate with meaningful argument names and documentation. — Evk, Feb 09 '18 at 21:32
I am no longer fan of delegates. It seems easier to use class with properties instead of set of parameters. This way at least it is clear what data is coming. — Optional Option, Feb 09 '18 at 22:22

score 1 · Answer 1 · edited Oct 11 '22 at 18:34

In short - not possible. Few possible workarounds:

Use a class or a structure instead of multiple parameters. Eg. instead of Action<int,int,int> use Action<ThreePigletsClass>
Minimize the number of parameters if possible. Maybe some are not necessary and simple Action would work.
Write parameter comments... which does not help much but gets you Stackoverflow points.
If not alergic to delegates use them instead.

score 1 · Accepted Answer · answered Nov 14 '21 at 10:38

You can use a nested structure.

/// <summary>
/// Does something useful.
/// </summary>
/// <param name="c">A constant</param>
/// <param name="someAction">
///     Here is an action.
///     <param name="someAction arg1">Count</param>
///     <param name="someAction arg2">Length</param>
///     <param name="someAction arg2">Content</param>
/// </param>
public void Do(int c, Action<int,int,string> someAction){}

It looks like this in the editor:

However, for complex structures, this is harder to maintain in the long run. If the context is not apparent intuitively, it is better and safer to create a class.

public class MyActionArgs : ActionArgs
{
    public MyActionArgs(int count, int length, string content)
    {
        Count = count;
        Length = length;
        Content = content ?? throw new ArgumentNullException(nameof(content));
    }

    public int Count { get; }
    public int Length { get; }
    public string Content { get; }
}

public void Do(Action<MyActionArgs> myAction){}

XML documentation of Action parameters in C#

2 Answers2