Documenting extension methods

Sep 6, 2011 at 8:24 AM

Hi!

When I write a conceptual topic, is it possible to reference an extension method?

Thanks!

ulu

Sep 6, 2011 at 8:55 AM
Edited Sep 6, 2011 at 8:58 AM

Hello ulu,

Yes, it is possible. What problem are you having? This is a simple demonstration of how it is done.
I have created a sample Class library project and added an extension method sample from the MSDN as

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace ClassLibrary1
{
    /// <summary>
    /// MyExtensions summary.
    /// </summary>
    public static class MyExtensions
    {
        /// <summary>
        /// Summary for WordCount.
        /// </summary>
        /// <param name="str">Instance of the string class.</param>
        /// <returns>The word count</returns>
        public static int WordCount(this String str)
        {
            return str.Split(new char[] { ' ', '.', '?' }, StringSplitOptions.RemoveEmptyEntries).Length;
        }
    }

    /// <summary>
    /// Summary for Class1.
    /// </summary>
    public class Class1
    {
        /// <summary>
        /// Initializes a new instance of the <see cref="Class1"/> class.
        /// </summary>
        public Class1()
        {   
        }
    }
}

The following XML comment will be generated...

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>ClassLibrary1</name>
    </assembly>
    <members>
        <member name="T:ClassLibrary1.MyExtensions">
            <summary>
            MyExtensions summary.
            </summary>
        </member>
        <member name="M:ClassLibrary1.MyExtensions.WordCount(System.String)">
            <summary>
            Summary for WordCount.
            </summary>
            <param name="str">Instance of the string class.</param>
            <returns>The word count</returns>
        </member>
        <member name="T:ClassLibrary1.Class1">
            <summary>
            Summary for Class1.
            </summary>
        </member>
        <member name="M:ClassLibrary1.Class1.#ctor">
            <summary>
            Initializes a new instance of the <see cref="T:ClassLibrary1.Class1"/> class.
            </summary>
        </member>
    </members>
</doc>

Hope you can see the extension method, WordCount, this is how I used it in the MAML...

<?xml version="1.0" encoding="utf-8"?>
<topic id="8add6948-2a00-4b24-a658-3b47d8d12e5d" revisionNumber="1">
  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" 
  xmlns:xlink="http://www.w3.org/1999/xlink">
    <introduction>
      <para>An introduction</para>
    </introduction>
    <section>
      <title>Test title</title>
      <content>
        <para>Test Contents</para>
      </content>
    </section>
    
    <relatedTopics>
    <!-- This is the link -->
     <codeEntityReference>M:ClassLibrary1.MyExtensions.WordCount(System.String)</codeEntityReference>

    </relatedTopics>
  </developerConceptualDocument>
</topic>

And it works without any problem.

Best regards,
Paul. 

Sep 6, 2011 at 8:59 AM

Thanks Paul!

Just to clarify: when I compile the Introduction topic, the link would display like "String.WordCount" and not "ClassLibrary1.MyExtensions.WordCount(System.String)"?

ulu

Sep 6, 2011 at 9:14 AM

No, in the above sample it will display as WordCount(String).

In your reference documentations it is still part of MyExtensions class, and not of the String class.
The extension method stuff is only a "syntax sugar" handled at compile time to simplify the coding...

If you write, say...

public int Count(string test)
{
    return test.WordCount();
}

The IL will look like this...there is no magic in extension method!!

.method public hidebysig 
	instance int32 Count (
		string test
	) cil managed 
{
	// Method begins at RVA 0x2090
	// Code size 12 (0xc)
	.maxstack 1
	.locals init (
		[0] int32 CS$1$0000
	)

	IL_0000: nop
	IL_0001: ldarg.1
	IL_0002: call int32 ClassLibrary1.MyExtensions::WordCount(string)
	IL_0007: stloc.0
	IL_0008: br.s IL_000a

	IL_000a: ldloc.0
	IL_000b: ret
}

Best regards,
Paul. 

Sep 6, 2011 at 9:20 AM
Edited Sep 6, 2011 at 9:20 AM

Thanks Paul, I understand that the ext method is just a syntactic sugar, but I want my users to use it as it is supposed to be used, as an extension method. I thought that there might me some MAML notation that would instruct the help building system to display the link the "sweet" way.

I guess I'll have to use plain links then..

Thanks a lot for your help!

Sep 6, 2011 at 9:35 AM

When the user click on the method it is documented as extension method in the reference document,
and I think anyone who knows extension methods will understand it - since it is the same in MSDN.

>> I guess I'll have to use plain links then

Just be careful since it might not always work as you move from say Help1 to Help3.

Best regards,
Paul.