How to use IEnumerable<String> in documenting code

Question

I have this method which I am trying to generate documentation.

    /// <summary>
    /// This method demonstrates taking a Func as argument and perform that action(Func) on a list of strings.</summary>
    /// <param name="listOfStrings"> ... </param>
    /// <param name="ActionToPerformOnEach"> ... </param>
    /// <returns>Returns an <see cref="IEnumerable{String}" /> which has elements that resulted due to the Func action </returns>
    public static IEnumerable<String> ActOnListWithFunc(List<string> listOfStrings, Func<string, string> ActionToPerformOnEach) {
        foreach (string s in listOfStrings) {
            string actedString = ActionToPerformOnEach(s);
            yield return actedString;
        }
    }

This generates documentation like this (only Return Value section is shown)

Return Value
Type: IEnumerable<String>
Returns an IEnumerable<T> which has elements that resulted due to the Func action

Where I am describing the return value of the method, I want to use IEnumerable<string> but if you look the desscription it is generating IEnumerable<T>. The Type: (second line above) although is been picked up properly as IEnumerable<string>. Just the description line for the return value is not correct.

How do we describe IEnumerable<string> or IEnumerable<int> or any other specific type of enumeration in descriptions of parameters or return values, that is betwween <param> </param> or <returns> </returns> tags of the Method being documentated.

Covalence

possible duplicate of How to reference generic classes and methods in xml documentation – Scaife

I am already using <see cref="IEnumerable{String}"> in my Returns attribute for the method, but its not showing the specific generic type (string). Please see the third line of the second patch of code posted. Its reads IEnumerable<T> instead of IEnumerable<String> – Covalence

Answer 1

You can show the appropriate text using <see cref="IEnumerable{String}">IEnumerable&lt;string&gt;</see>. However the link will still be to IEnumerable<T> as there is no specific documentation for IEnumerable<string>

Oglesby

I think, Link to IEnumerable<T> may be acceptable, but those character entities (&lt; and &gt;) are a little ugly. But in any case your solution does work and I get IEnumerable<string> as desired. Still I will wait for some time, for alternatives if any, before marking as accepted solution. – Covalence

Answer 2

We would just write

/// <returns>Returns an <see cref="IEnumerable{T}" /> of type <see cref="string"/> which has elements that resulted due to the Func action.</returns>

This creates a reference to both IEnumerable<out T> and string.

The solution proposed by John Koemer has the disadvantage that IntelliSense does not do anything with the IEnumerable%lt;string%gt; part.

Labyrinthodont