Использование doxygen для создания документации для существующего кода C # с комментариями XML - PullRequest
9 голосов
/ 31 августа 2011

Я прочитал везде , что doxygen - это способ создания документации для кода C #. У меня есть один интерфейс, который я хочу сначала документировать (детское пошаговое руководство), и он уже содержит комментарии XML (///).

Из-за огромного количества постов и доступной информации (включая doxygen.org), в которых говорится, что эти комментарии уже поддерживаются, я удивлен, что при запуске doxywizard выдается сообщение об ошибке типа «предупреждение: Compound Company :: Product: : MyInterface не задокументирован ".

Это заставляет меня поверить, что я как-то неправильно понял документацию XML (надеюсь, нет, согласно MSDN Я говорю о правильной вещи), или я неправильно настроил doxywizard.

Сначала я запустил doxywizard через вкладку Wizard и указал, что хочу поддерживать C # / Java. Когда я запускаю его, моя HTML-страница остается пустой, предположительно из-за ранее упомянутых предупреждений. Затем я попытался указать один файл на вкладке «Эксперт» и снова запустил - то же самое поведение.

Может кто-нибудь сказать мне, какой переключатель или настройка мне не хватает, чтобы получить doxygen для генерации HTML?

Вот пример того, как документированное свойство / метод выглядит в моем интерфейсе:

/// <summary>
/// Retrieve the version of the device
/// </summary>
String Version { get; }

/// <summary>
/// Does something cool or really cool
/// </summary>
/// <param name="thing">0 = something cool, 1 = something really cool</param>
void DoSomething( Int32 thing);

У меня есть комментарий над интерфейсом, например:

/// <summary>
/// MyInterface
/// </summary>
public interface MyInterface {...}

1 Ответ

9 голосов
/ 31 августа 2011

Я думаю, я понял это.В руководстве по Doxygen сказано, что EXTRACT_ALL = 0 является настройкой по умолчанию, и в этом случае «будет генерировать документацию только для задокументированных членов, файлов, классов и пространств имен».Теперь, я думал , что я их правильно задокументировал, но, видимо, нет.Я просто включил EXTRACT_ALL, и предупреждения исчезли, и я получил документацию для моего интерфейса!Я прочитал о «специальных блоках документации», думая, что что-то упустил (благодаря комментарию Эрика Фарра), но он не упомянул о выполнении чего-то особенного для кода C #, поэтому я предполагаю, что значение по умолчанию для EXTRACT_ALL должновсе еще работал.

...