Generic parameters lead to confusion (on my side?)

Topics: Developer Forum, User Forum
Sep 21, 2010 at 1:59 PM

Has anybody an idea what happens here (who is the bad guy in this chain?)

Starting with the following instrumented C# (4.0) code:

/// <summary>
/// The Ka.
/// </summary>
/// <typeparam name="T">The type.</typeparam>
public static class Ka<T>
{
    /// <summary>
    /// Does the specified action.
    /// </summary>
    /// <param name="action">The action.</param>
    public static void Do(Action<T> action)
    {
    }

    /// <summary>
    /// Does the specified action.
    /// </summary>
    /// <param name="action">The action.</param>
    public static void Do(Action<T, T> action)
    {
    }
}
leading to a comment-doc-xml with something like the following (looks really pretty in my eyes) in it

<member name="M:Warn.Ka`1.Do(System.Action{`0})">
    <summary>
        Does the specified action.
    </summary>
    <param name="action">The action.</param>
</member>
<member name="M:Warn.Ka`1.Do(System.Action{`0,`0})">
    <summary>
        Does the specified action.
    </summary>
    <param name="action">The action.</param>
</member>
leading to these messages in in Build Output:
BuildReferenceTopics:
  BuildAssembler (v2.6.10621.1)
  Copyright ¸ Microsoft 2006
.... deleted for briefness ....
  Info: ShowMissingComponent: 
      [Sandcastle Help File Builder BuildAssembler Components, version 1.9.1.0]
      Show Missing Documentation Component. Copyright ¸ 2006-2010, Eric Woodruff, All Rights Reserved
      http://SHFB.CodePlex.com
.... deleted for briefness ....
  Info: BuildAssembler: Building topic M:Warn.Ka`1.Do(System.Action{`0})
  Info: BuildAssembler: Building topic M:Warn.Ka`1.Do(System.Action`2)
  Warn: ShowMissingComponent: Missing <summary> documentation for M:Warn.Ka`1.Do(System.Action`2)
  Warn: ShowMissingComponent: Missing <param name="action"/> documentation for M:Warn.Ka`1.Do(System.Action`2)
So .. my question: who's evil? (and what to do)

Coordinator
Sep 21, 2010 at 8:55 PM

It's could be the compiler's fault as it's outputing a different method signature in the XML comments than what Sandcastle finds and extracts from the assembly's metadata.  The VB.NET and C++ compilers have this problem too in a couple of instances.  For now, the only workaround is to fix the XML comments file so that the method ID matches the one generated by Sandcastle (M:Warn.Ka`1.Do(System.Action`2).

Eric

 

Nov 20, 2010 at 4:07 PM

Eric,

it seems that it's Sancastle which has a bug: `2 refers to the 3rd generic parameter and the class only has 1!

I've also seen examples where the generic parameter index changes depending on the number of generic parameters.

Patrick