How to show general comments on function overloads.

Question

I have created a function with some overloads. Now I want to add comments for each overload but not repeating summary content again and again. I only want parameter description to be given.

i.e.

    /// <summary>
    /// Binds Control With DataTable/DataSet Passed as a Parameter. DataTable/Control Should not be NULL.
    /// </summary>
    /// <param name="lbx">DropDownList control</param>
    /// <param name="dt">Object of DataTable from where value need be fetched.</param>
    /// <param name="displayMember">Display Member for the list</param>
    public static void Source(this DropDownList ddl, DataTable dt, string displayMember)
    {
     // do something.
    }

    /// <summary>
    /// Binds Control With DataTable/DataSet Passed as a Parameter. DataTable/Control  
    /// </summary>
    /// <param name="lbx">DropDownList  control</param>
    /// <param name="dt">Object of DataTable from where value need be fetched.</param>
    /// <param name="displayMember">Display Member for the list</param>
    /// <param name="_setDefaultItem">If True Sets the default value as -1 and corresponding string</param>
    public static void Source(this DropDownList ddl, DataTable dt, string displayMember, bool _setDefaultItem)
    {
     //do something
    }

Here I dont want to write summary section again and again but want to write comments on parameter portion only. Rest should be visible for every overload.

Is there any way to do?

Answer 1

You can use include tag to achieve this.

Create a xml file with common summary, parameter descriptions of your overloaded methods.

And reference this in your every overloaded method, and add method specific param list comments alone in your overloaded method.

/// <include file='common_tag.doc' path='MyDocs/MyMembers[@name="source"]/*' />
public static void Source(this DropDownList ddl, DataTable dt, string displayMember) 
{ 
 // do something. 
} 

/// <include file='common_tag.doc' path='MyDocs/MyMembers[@name="source"]/*' />
/// <param name="_setDefaultItem">If True Sets the default value as -1 and corresponding string</param> 
public static void Source(this DropDownList ddl, DataTable dt, string displayMember, bool _setDefaultItem) 
{ 
 //do something 
} 

And ur xml file is something like

<MyDocs>

<MyMembers name="source">
<summary>
Binds Control With DataTable/DataSet Passed as a Parameter. DataTable/Control Should not be NULL
</summary>
<param>....</param>
</MyMembers>


</MyDocs>

i haven't tested this... you may try this

Cheers