Документация Sandcastle в проекте ExcelDNA

Question

У меня есть проект ExcelDNA , который добавляет ленту с функциями udf в Excel.

Использование ExcelDNA.Documentation Я создал базовую документацию для проекта,Но я считаю, что документация ограничена, и я начал использовать Sandcastle поверх него.Но я не могу заставить Sandcastle найти комментарии XML над каждой функцией.

Ниже приведена простая функция с документацией ExcelDNA и Sandcastle:

/// <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)
{

Мне нужны атрибуты ExcelDNA, так как они отображаются в Excel в качестве всплывающей справочной информации при выборе функции.

Атрибуты ExcelDNA блокируют Sandcastle от поиска комментариев XML для каждой функции?

Answer 1

Я предполагаю, что вы используете Visual Studio.Вы знаете - XML-комментарии должны быть добавлены в ваш код для документирования различных типов и их членов.

Кроме того, вы должны включить вывод файла XML-комментариев для проекта.

1. В обозревателе решений щелкните правой кнопкой мыши проект и выберите Свойства.
2. Выберите страницу свойств сборки.
3. В разделе «Вывод» установите флажок «Далее».в текстовое поле файла документации Xml и укажите имя для файла XML.Хотя это и не обязательно, общепринятым условием является присвоение имени файлу комментариев XML после связанной сборки (кроме случаев с расширением .xml).Имя сборки можно найти на странице свойств приложения.
4. Если у вас есть решение с несколькими проектами, которые необходимо документировать, повторите описанные выше шаги для каждого проекта в решении.Рекомендуется дать каждому файлу XML-комментариев каждого проекта уникальное имя.

Для использования Sandcastle вы найдете пошаговое руководство Создание первого проекта .

Вывод базовых файлов HTML может быть достигнут с помощью Sandcastle, НЕ использующего Очистить промежуточные файлы после успешной сборки в Свойства проекта> Сборка.

Создание полезной помощиконтент очень трудоемкий и имеет кривую обучения. Я рекомендую с использованием ExcelDna.Documentation , поскольку базовые файлы HTML имеют непосредственно назначенные имена файлов, и уже создан контекстный идентификатор (см. Раздел [ALIAS] и [MAP] в * .hhpфайл).

[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

Для получения дополнительной информации я приложил следующий пример кода и снимки экрана:

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;
        }

    }
}

Полученный в результате CHM с использованием ExcelDna.Documentation:

Вариант использования Excel с открытым окном справки:

Полученный CHM с использованием Sandcastleis ( обратите внимание: на этом этапе не включен Context-ID! )