How to use IEnumerable 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.

possible duplicate of [How to reference generic classes and methods in xml documentation](http://stackoverflow.com/questions/532166/how-to-reference-generic-classes-and-methods-in-xml-documentation) — Charles Mager, Jun 29 '14 at 10:33
I am already using 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 instead of IEnumerable — Jatin, Jun 29 '14 at 10:52

John Koerner · Accepted Answer · 2014-06-29T11:37:30.797

14

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

edited Jun 29 '14 at 11:37

answered Jun 29 '14 at 10:58

John Koerner

37,428
8
84
134

I think, Link to IEnumerable may be acceptable, but those character entities (< and >) are a little ugly. But in any case your solution does work and I get IEnumerable as desired. Still I will wait for some time, for alternatives if any, before marking as accepted solution. – Jatin Jun 29 '14 at 11:13

score 2 · Answer 2 · answered Nov 09 '20 at 14:49

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.

How to use IEnumerable in documenting code

2 Answers2