A generic List<MyObject> problem

Topics: Developer Forum
Jan 23, 2008 at 11:18 AM
Hello!

I've a problem to document a generic List<MyObject>. Here's a simple dummy example to show what I mean:



using System;
using System.Collections.Generic;

namespace ConsoleApplication1
{
/// <summary>
/// Conntains some classes
/// </summary>
public class Program
{
/// <summary>
/// The main program
/// </summary>
/// <param name="args">The args.</param>
public static void Main(string[] args)
{
}

/// <summary>Dummy method takes a <see cref="List{MyObject}"/>.</summary>
/// <param name="mo1">The mo1 parameter</param>
/// <returns>A list of <see cref="List{MyObject}"/></returns>
public List<MyObject> Dummy(MyObject mo1)
{
return new List<MyObject>();
}
}

/// <summary>
/// My dummy object class
/// </summary>
public class MyObject
{
}
}



The creation of the help files work fine. But I e.g. get the following for the return type of method Dummy():

_Return Value
A list of List<T>

But I would like to get:

A list of List<MyObject>


Is there a way to do this?!?

Thx, Mac
Coordinator
Jan 23, 2008 at 8:02 PM
Edited Jan 23, 2008 at 8:03 PM
The compiler will translate List{MyObject} to a basic reference to List{T} in the generated XML comments file. If you want it to say "MyObject" in the help file, change the tag to use the inner text form:

<see cref="List{T}">List&lt;MyObject&gt;</see>.

Note that the link will still go to List<T> as List<MyObject> doesn't really exist in the assembly. The only way to get a concrete version would be to create a class derived from List<MyObject> and use that instead.

Eric
Mar 20, 2008 at 2:20 PM
How do you document a Generic collection so it becomes a link? I have a property like this:

''' <summary>
''' Gets the collection of Clients managed by this class.
''' </summary>
''' <value>A <see cref="System.Collections.Generic.Dictionary(Of String, Object)"/>.</value>
''' <remarks></remarks>
Public ReadOnly Property Clients() As Dictionary(Of String, Object)
Get
Return Me._Clients
End Get
End Property

Whenever the documentation is created I just get text and no link. Thanks for your help!
Coordinator
Mar 20, 2008 at 4:00 PM
As above, use curly braces and, in the case of the dictionary, two names to represent the types. For example:

<see cref="System.Collections.Generic.Dictionary{TKey, TValue}"/>

If you want it to say "Of String, Object", use the inner text to specify the text you want displayed for the link.

<see cref="System.Collections.Generic.Dictionary{TKey, TValue}">Dictionary(Of String, Object)</see>

If that doesn't work, let me know and I'll go try it out. Sometimes, the VB.NET compiler doesn't always generate the XML comment names the same way.

Eric