Persuading IEnumerable<t> to show more detail

Topics: Developer Forum
Feb 27, 2012 at 7:18 PM

I'm trying to get some useful documentation where a method is returning an IEnumerable.  So, in my XML comments, I have this:

/// The <see cref="IEnumerable{short}"/> which blah blah blah

which appears in the help file as:

The [!:IEnumerable<short>] which blah blah blah

Reducing the XML comment to a simplified:

/// The <see cref="IEnumerable{T}"/> which blah blah blah

causes the help file to show:

The IEnumerable(T) which blah blah blah

with the hyperlink going off to MSDN talking about IEnumerable as expected.  My real world (unsimplified) example would be:

/// The <see cref="IEnumerable{Some.Namespace.Sometype}"/> which blah blah blah

I was rather hoping that I'd end up with two "nested" hyperlinks - one going to IEnumerable in MSDN and the other going to Sometype in my own documentation. 

Am I expecting too much here, or am I missing something obvious?

Thanks, Nick.

Feb 27, 2012 at 9:11 PM

The XML comments are produced by the compiler and, as you may have noticed, it won't allow you to specify a type as the generic argument in the cref attribute and will produce a warning stating that it must be an identifier (i.e. T).  It's expecting a reference to the generic type and not a concrete type that's derived from the generic type produced by the compiler.  As such, you get the invalid reference with the "!" prefix instead.  It's possible that you could create a build component to look for these invalid links and parse them for the necessary information to make an attempt at converting them into something useful.  However, that could prove quite difficult as you'd have to parse the text and translate data types to the actual framework type (short to System.Int16 etc.) and would have to deal with types that were not fully qualified and try to resolve them to types within your project or the .NET Framework.