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.

possible duplicate of How to reference generic classes and methods in xml documentation — Charles Mager
– Charles Mager, Commented Jun 29, 2014 at 10:33
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> — Jatin
– Jatin, Commented Jun 29, 2014 at 10:52

John Koerner · Accepted Answer · 2014-06-29 11:37:30Z

15

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, 2014 at 11:37

answered Jun 29, 2014 at 10:58

John Koerner

38.2k8 gold badges92 silver badges142 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Jatin Over a year ago

I think, Link to IEnumerable<T> may be acceptable, but those character entities (< and >) 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.

comecme · Accepted Answer · 2020-11-09 14:49:53Z

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.

Collectives™ on Stack Overflow

How to use IEnumerable<String> in documenting code

2 Answers 2

1 Comment

Comments

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

Comments

Linked

Related