Sandcastle XML Comments Guide
|
overloads |
This element is used to define the content that should appear on the auto-generated overloads topic for a given set of member overloads.
Syntax
This top-level element is valid on any overloaded member. However, it should only appear on one of the members in each overload set. The member on which the element appears should have its own set of member-specific XML comments as well.
<overloads>description</overloads> or <overloads> <summary> Summary description </summary> [<remarks>Optional remarks</remarks>] [<example>Optional examples</example>] [... other top-level comments elements as needed ...] </overloads>
In its simplest form, the element contains a description that will appear as the summary in the auto-generated overloads member topic. The expanded form allows you to include any top-level XML comments elements as you would on a standard member. These elements will be formatted in an identical fashion and will appear in the auto-generated overloads member topic.
Example
// Simple overloads form /// <summary> /// This is used to sum an enumerable list of values /// </summary> /// <param name="values">The values to sum</param> /// <returns>The sum of the values</returns> /// <overloads>There are two overloads for this method</overloads> /// <conceptualLink target="5b11b235-2b6c-4dfc-86b0-2e7dd98f2716" /> public int SumValues(IEnumerable<int> values) { return values.Sum(v => v); } /// <summary> /// This is used to sum two enumerable list of values /// </summary> /// <param name="firstValues">The first set of values to sum</param> /// <param name="secondValues">The second set of values to sum</param> /// <returns>The sum of the values from both enumerable lists</returns> /// <conceptualLink target="5b11b235-2b6c-4dfc-86b0-2e7dd98f2716" /> public int SumValues(IEnumerable<int> firstValues, IEnumerable<int> secondValues) { return firstValues.Sum(v => v) + secondValues.Sum(v => v); } // Expanded overloads form /// <summary> /// This is used to average an enumerable list of values /// </summary> /// <param name="values">The values to average</param> /// <returns>The average of the values</returns> /// <overloads> /// <summary> /// These methods are used to compute the average of enumerable lists of integers /// </summary> /// <remarks> /// These methods serve no other purpose than to demonstrate the use of the /// <c>overloads</c> XML comments element. /// </remarks> /// <example> /// <code language="cs"> /// SampleClass sc = new SampleClass(0); /// /// Console.WriteLine("Average: {0}", sc.Average(new[] { 1, 2, 3, 4 })); /// Console.WriteLine("Average: {0}", sc.Average(new[] { 1, 2, 3, 4 }, /// new[] { 10, 20, 30, 40})); /// </code> /// </example> /// </overloads> /// <conceptualLink target="5b11b235-2b6c-4dfc-86b0-2e7dd98f2716" /> public double AverageValues(IEnumerable<double> values) { return values.Average(v => v); } /// <summary> /// This is used to get the average of two enumerable list of values /// </summary> /// <param name="firstValues">The first set of values to average</param> /// <param name="secondValues">The second set of values to average</param> /// <returns>The average of the values from both enumerable lists</returns> /// <conceptualLink target="5b11b235-2b6c-4dfc-86b0-2e7dd98f2716" /> public double AverageValues(IEnumerable<double> firstValues, IEnumerable<double> secondValues) { return firstValues.Concat(secondValues).Average(v => v); }
See Also