Проект веб-сайта: хотите создать XML-документацию при сборке

По причинам наследия я поддерживаю проект веб-сайта, для которого я хочу предоставить обновленную документацию из комментариев к документации XML. Я так понимаю, что могу сделать это, настроив раздел <compilers> в web.config. Наконец я дошел до этой точки:

  <system.codedom>
    <compilers>
      <compiler
        language="c#;cs;csharp"
        extension=".cs"
        type="Microsoft.CSharp.CSharpCodeProvider"
        compilerOptions="/optimize /doc:C:\temp\my-output-here.xml"
        warningLevel="1" />
    </compilers>
  </system.codedom>

Теперь, когда я запускаю веб-сайт (и, таким образом, вызываю своевременную компиляцию), я получаю XML-файл в запрошенном месте, но он минимален:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>App_global.asax.abqhzva4</name>
    </assembly>
    <members>
    </members>
</doc>

Похоже, что тег <compiler> не совсем то, что я хочу. Он должен генерировать XML для самой папки проекта, а не для файлов .cs, иначе он будет перезаписан каждой единицей компиляции, а я вижу только тривиальный последний, или ... я не знаю. Я не уверен. Этот тег конфигурации плохо документирован.

Короче говоря, я ищу способ получить XML-документацию для всех .cs файлов в этом проекте веб-сайта. Не имеет значения, все ли это в одном файле, в отдельных файлах или даже в памяти во время выполнения.

Я осведомлен о предыдущий вопрос по этому поводу, но указанная там ссылка была перенаправлена ​​на сайт Sandcastle. Это здорово, но это намного больше, чем я собираюсь использовать в этом проекте. Достаточно просто получить XML-документацию во время сборки или выполнения.

Тогда мой вопрос: что мне нужно сделать, чтобы получить запись конфигурации <compiler> для создания XML-документов для проекта веб-сайта?


web-site-project visual-studio-2012 xml-documentation
person catfood    schedule 18.09.2015    source источник

Ответы (1)


arrow_upward
1
arrow_downward

У меня тоже есть неприятный обходной путь ... Но начнем!

1. Загрузите последнюю версию установщика Sandcastle с этой страницы - https://github.com/EWSoftware/SHFB/releases

2. Разархивируйте и запустите установщик.

3. Скопируйте EWSoftware.CodeDom.dll в \bin каталог своего веб-сайта. Расположение этого файла по умолчанию - C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\Extras\EWSoftware.CodeDom.dll.

4. Измените web.config следующим образом:

<configuration>
  <system.codedom>
    <compilers>
      <compiler language="c#;cs;csharp" extension=".cs"
        compilerOptions="/docpath:C:\Publish\Docs"
        type="EWSoftware.CodeDom.CSharpCodeProviderWithDocs, EWSoftware.CodeDom"
      >
        <!-- NOTE: Change version value as needed (v3.5, v4.0, etc.) -->
        <providerOption name="CompilerVersion" value="v4.0"/>
      </compiler>
    </compilers>
  </system.codedom>
</configuration>

Источник: http://ewsoftware.github.io/EWSoftwareCodeDom/html/40ba6bda-95d6-4a64-834f-f7cedcb589d1.htm

5. Восстановите решение и вуаля! Папка, указанная с помощью параметра /docpath, будет содержать вашу XML-документацию.

person dana    schedule 25.09.2015
comment
Мне это нравится! Конечно, это означает установку всего Sandcastle, но в результате не требует особого обслуживания. Неплохо. - person catfood; 27.09.2015
comment
Спасибо :). У меня есть подозрение, что каждый каталог создается с помощью нового вызова csc.exe. Используя исходную технику, при создании каждой папки выходной XML-файл перезаписывает XML-файл предыдущей папки. Итак, все, что вы видите, - это XML-файл последней скомпилированной папки. Отсюда необходимость в компиляторе Sandcastle, который дает каждой папке XML-файл с уникальным именем. - person dana; 28.09.2015
comment
Или, может быть, для каждого файла делается вызов csc.exe? Дело в том, что если выполняется несколько вызовов, вам нужен способ указать XML-файл назначения для каждого вызова. - person dana; 28.09.2015