Sandcastle documentation in a ExcelDNA project

Question

I have a ExcelDNA project which adds a ribbon with udf functions in Excel.

Using ExcelDNA.Documentation I've created some basic documentation for the project. But I find the documentation posibilites limited, and I've started to use Sandcastle on top of it. But I can't get Sandcastle to find the XML comments above each function.

Below is a simple function with both ExcelDNA and Sandcastle documentation:

/// <summary>
/// Returns the name of a chemical element.
/// </summary>
/// <param name="symbol">Symbol of an element</param>
/// <returns></returns>
[ExcelFunctionDoc(Name = "zAtomicName", Description = "Returns the name of a chemical element.", Category = "Chemistry", HelpTopic = "xxx.chm!2002")]
public static object zAtomicName([ExcelArgument(Name = "symbol", Description = "is the symbol of the element")] object input)
{

I need the ExcelDNA attributes as they are shown in Excel as popup help information when you choose a function.

Is the ExcelDNA attributes blocking Sandcastle from finding the XML comments for each function?

Answer 1

I assume you're using Visual Studio. You know - XML comments must be added to your code to document the various types and their members.

In addition, you must enable XML comments file output for the project.

1. In the Solution Explorer, right click on the project and select Properties.
2. Select the Build property page.
3. In the Output section, check the checkbox next to the Xml documentation file text box and specify a name for the XML file. Although not required, a common convention is to name the XML comments file after the related assembly (except with a .xml extension). The assembly name can be found on the Application property page.
4. If you have a solution with multiple projects that need to be documented, repeat the above steps for each project in the solution. It is recommended that you give each project's XML comments file a unique name.

For using Sandcastle you'll find a walkthrough Creating Your First Project.

The output of the underlying HTML files can be achieved with Sandcastle NOT using the Clean intermediate files after a successful build option at Project Properties > Build.

Creating good help content is very time-consuming and has a learning curve. I recommend using ExcelDna.Documentation because the underlying HTML files have directly assigned file names and a context ID is already generated (see [ALIAS] and [MAP] section in the *.hhp file).

[OPTIONS]
Compatibility=1.1 or later
Compiled file="Excel-DNA-Library-AddIn.chm"
Contents file=Table of Contents.hhc
Default topic=index.htm
Display compile progress=No
Language=0x409 English (United States)

[INFOTYPES]

[ALIAS]
Topic20000=MyAddTwoIntegers.htm
Topic10000=MyHelloWorld.htm

[MAP]
#define Topic20000 20000
#define Topic10000 10000

For further information I attached the following example code and screenshots:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using ExcelDna.Integration;
using ExcelDna.Documentation;

namespace Excel_DNA_Library
{
    /// <summary>
    /// This code is only used as test case for Excel-DNA and Sandcastle XML-comments.
    /// </summary>
    /// <remarks>
    /// <para>This class can welcome you and add.</para>
    /// <para>Nothing else is possible.</para>
    /// </remarks>
    public class UDFHelper
    {
        /// <summary>
        /// <c>MyHelloWorld</c> - my first .NET function using Excel-DNA.
        /// </summary>
        /// <param name="name">Your first name.</param>/// 
        /// <returns>A welcome string and text from user input.</returns>
        /// <example>
        /// <code>
        /// =MyHelloWorld("www.help-info.de");
        /// </code>
        /// </example>
        [ExcelFunction( Name = "MyHelloWorld",
                        Category = "Text",
                        Description = "Welcome - my first .NET function using Excel-DNA.",
                        HelpTopic = "Excel-DNA-Library-AddIn.chm!10000")]

        public static string SayHello(string name)
        {
            return "You are welcome " + name;
        }

        /// <summary>
        /// <c>MyAddTwoIntegers</c> - my second .NET function using Excel-DNA.
        /// </summary>
        /// <param name="a">The first integer.</param>
        /// <param name="b">The second integer.</param>
        /// <returns>The sum of two integers.</returns>
        /// <example>
        /// <code>
        /// =MyAddTwoIntegers(4, 5);
        /// </code>
        /// </example>
        [ExcelFunctionDoc(Name = "MyAddTwoIntegers",
                          Category = "Math",
                          Description = "Add two integers - my second .NET function using Excel-DNA.",
                          HelpTopic = "Excel-DNA-Library-AddIn.chm!20000",
                          Summary = "really all it does is add two number ... I promise.",
                          Returns = "the sum of the two arguments")]            

        public static int Add(int a, int b)
        {
            return a + b;
        }

    }
}

The resulting CHM using ExcelDna.Documentation is:

An Excel use case with the help viewer window opened:

The resulting CHM Using Sandcastle is (please note: no Context-ID is included at this stage!)