Referring to a generic type of a generic type in C# XML documentation?

Question

/// I am following a turorial from youtube, https://www.youtube.com/watch?v=nUbNn0voiBI&t=88s and faced an error,

Proxy error: Could not proxy request /notes from localhost:3000 to https://localhost:3001/. See https://nodejs.org/api/errors.html#errors_common_system_errors for more information (EPROTO).

function Notes(){
    const [notes, setNotes] = useState([{
        name: '',
        email: '',
        phone: '',
        message: ''
    }])

    useEffect(() => {
        fetch("/notes").then(res => {
            if(res.ok) {
                return res.json()
            }
        }).then(jsonRes => setNotes(jsonRes));
    })

    return <div className="container">
        <h1>Notes page</h1>
        {notes.map(note => 
            <div>
                <h1>{note.name}</h1>
                <p>{note.email}</p>
                <p>{note.phone}</p>
                <p>{note.message}</p>
            </div>            
            )}
    </div>
}

export default Notes;```

Solution 1

There seems to be no way to refer to a generic of a generic in XML documentation, because actually, there's no way to refer to a generic of any specific type.

Lasse V Karlsen's answer made it click for me:

If you write <see cref="IEnumerable{Int32}" />, the compiler just uses "Int32" as the type parameter name, not the type argument. Writing <see cref="IEnumerable{HelloWorld}" /> would work just as well. This makes sense because there is no specific page in MSDN for "IEnumerable of int" that your documentation could link to.

To document your class properly, I think you'd have to write something like:

<summary>
Returns an <see cref="IEnumerable{T}" /> of <see cref="KeyValuePair{T,U}" /> 
of <see cref="String" />, <see cref="Int32" />.
</summary>

I hope you like text.

Solution 2

What exactly would you like it to link to?

There's no such thing in the documentation as a Expression<Func<T>>, so obviously a link to that would not work.

You can link to Expression<TDelegate> because that exists.

As for what works or not, neither of the following works in Visual Studio 2008 / .NET 3.5 for me:

/// <see cref="Expression&lt;Func&lt;T&gt;&gt;"/>.
/// <see cref="Expression{Func{T}}"/>.

But this works:

/// <see cref="Expression{T}"/>.

so apparently the generic type parameter doesn't have to the same as the one in the declaration.

Solution 3

// Use "&lt;" instead of "<" symbol and "&gt;" instead of ">" symbol.

// Sample:

<see cref="Expression&lt;Func&lt;T, bool&gt;&gt;"/>

Solution 4

I'm running into this now, as I have a function that returns a List<List<byte>>. Yeah, it's ugly, but I didn't write it. Standard disclaimer, I know.

Anyway, in VS 2017 with R# Ultimate 2017.1, this doc comment...

<returns><see cref="List{List{Byte}}" /> of split frames</returns>

...gives me a syntax error. However, this...

<returns><see><cref>List{List{byte}}</cref></see> of split frames</returns>

...does not. Eeeenteresting.

Still ugly? Yes.

As ugly? I think it's less horrible than using < and > myself....

Solution 5

Don't use an empty see element (<see cref="..." />). Instead, put text inside the see element

<see cref="IEnumerable{T}">IEnumerable</see>&lt;<see cref="..."/>$gt;

View more solutions

Comments

[Rory MacLeod]

I was about to ask the same question. It took me a while to find this one because the title isn't very keyword-y. Can I suggest, "How do I refer to a generic type of a generic type in C# XML documentation"? You might also add the "generics" tag. I don't have the rep to do it myself.

[Alex]

<see cref="Expression{Func{T, Boolean}}"/> works fine in VS2015, Reshaper 9

[BrainSlugs83]

The message says "Type parameter declaration must be an identifier not a type"; for example, if you have List{Int32}, it should be, List{T} because there's not an actual List{Int32} class sitting around in the code base somewhere, there's only a List{T}. Int32 is a type, T is an identifier.

[Shubham J.]

Might be the response you are getting from API call is not array or might be undefined. Because, .map will run only on array. Can you check what response are you getting from API?

[Lemon]

Oh my... that is ugly... but it does work =/ Why does it accept the { } for one type but not more, kind of?

[Lemon]

Sure about what? Like I said, I get no red squiggly line when using Expression{TDelegate} or for example List{String}. Actually, when I write <see and press enter, it auto completes to <see cref=""/>. When I then write List and press enter, it autocompletes to List{T}.

[Lasse V. Karlsen]

That is because "String" is then just used as the generic type name. Try List<DOOBIEDOOBIEDOO> and it'll work just as great.

[Lemon]

No I hate text, that's why I asked this question. Oh well... maybe in a future version of xml-doc :p

[Dan Is Fiddling By Firelight]

Visual studio 2010 is flagging stuff like this with a warning. Apparently MS felt that not doing so in 2008 was a bug.

[Max Toro]

No need for >, this is well-formed XML: <see cref="Expression&lt;Func&lt;T, bool>>"/>

[DvS]

Unfortunately, nothing has changed in 2020, and this still seems to be the only real solution. Still can't reference generic types like Nullable<int> in cref XML comments.