Objective-C Генераторы документации: HeaderDoc против Doxygen vs. AppleDoc

Мне нужно реализовать решение для создания документации для моего рабочего места и сузить его до трех, упомянутых в названии. Мне удалось найти очень мало информации о формализованных сравнениях этих решений, и я надеюсь, что те из вас, у кого есть опыт работы в одном или нескольких из вышеперечисленных, могут взвесить:

Вот что мне удалось получить из моего первоначального прохода:

HeaderDoc Pros: совместим с существующими документами Apple, совместимость с созданием apple docset
HeaderDoc Cons: Трудно изменить поведение, проект активно не работает, многие из них отключаются (это значит, что что-то не хватает, хотя я не могу его количественно оценить).

Doxygen Плюсы: Активное сообщество поддержки b/c широко используемой базы, очень настраиваемое, большинство типов вывода (например, латекс и т.д.)
Doxygen Минусы: Делает работу, чтобы заставить ее выглядеть/вести себя в соответствии с документами яблок, совместимость с яблочными документами не так проста.

AppleDoc Плюсы: Выглядит в согласии с яблочными существующими документами, совместимостью с яблочными документами,
AppleDoc Минусы: Проблема с документированием typedefs, перечислений и функций, активно разрабатываемых

Звучит ли это правильно? Наше желаемое решение будет иметь:

Последовательный внешний вид с яблоками objective-c ссылка на класс
Возможность щелчка по ссылке, чтобы вытащить ссылку на документацию из Xcode, а затем ссылку на документ (как и на классы apple)
Умная обработка категорий, расширений и т.п. (даже пользовательские категории классов Apple)
Возможность создавать собственные страницы ссылок (например, эта страница: Загрузка..., которая может включать в себя изображения, и быть легко связанными с генерируемыми классами, например, как ссылка класса Java UIViewController ссылается на связанную страницу.
Простой запуск команд командной строки, которые могут быть интегрированы в скрипты сборки
Изящное обращение с очень большой кодовой базой

Основываясь на всей приведенной выше информации, любое из вышеперечисленных решений явно лучше других? Любые предложения или информация для добавления были бы чрезвычайно оценены.

Ответ 1

Как создатель и ведущий разработчик doxygen, позвольте мне также представить свою перспективу (очевидно, предвзято, -)

Если вы ищете 100% верную копию собственного стиля документации Apple, то AppleDoc - лучший выбор в этом отношении. С doxygen вам будет трудно найти тот же самый вид, поэтому я бы не рекомендовал попробовать.

Что касается Xcode docsets; Apple предоставляет инструкции, как установить это с помощью doxygen (написанное за время, когда Xcode 3 был выпущен). Для Xcode 4 есть также отличный справочник, как интегрировать doxygen.

Начиная с версии 1.8.0, doxygen поддерживает Markdown markup, а также большое количество дополнительных markup команды.

С помощью doxygen вы можете включить документацию на главной странице (@mainpage), а также на подстраницы (используя @subpage или @page). Внутри страницы вы можете создавать разделы и подразделы. Фактически, руководство пользователя doxygen было полностью написано с использованием doxygen. Кроме того, вы можете группировать классы или функции вместе (используя @defgroup и @ingroup), а внутри класса создавать пользовательские разделы (используя @name).

Doxygen использует файл конфигурации в качестве входных данных. Вы можете создать шаблон со значениями по умолчанию с помощью doxygen -g или использовать графический редактор для его создания и редактирования. Вы также можете передавать параметры через doxygen через script с помощью doxygen - (см. Вопрос 17 в FAQ для примера)

Doxygen не ограничивается Objective-C, он поддерживает большой диапазон языков, включая C, С++ и Java. Doxygen также не ограничивается платформой Mac, например. он работает также на Windows и Linux. Выход Doxygen также поддерживает больше, чем просто HTML; вы можете создавать PDF-выход (через LaTeX) или RTF и man-страницы.

Doxygen также выходит за рамки чистой документации; doxygen может создавать различные графики и диаграммы из исходного кода (см. dot связанные параметры). Doxygen также может создавать обзорную и синтаксическую выделенную версию вашего кода и перекрестно ссылаться на документацию (см. исходный браузер).

Doxygen очень быстро подходит для проектов малого и среднего размера (генерация диаграммы может быть медленной, но в настоящее время она работает на нескольких ядрах процессора параллельно, а графики с одного запуска повторно используются в следующем запуске). Для очень больших проектов (например, миллионы строк кода) doxygen позволяет разделить проекты на несколько частей и затем связать части вместе, как я объяснил здесь.

Хороший реальный пример использования doxygen для Objective-C можно найти здесь.

Развитие доксигена сильно зависит от отзывов пользователей. У нас есть активный список рассылки для вопросов и обсуждений и отслежыватель ошибок для обоих ошибок и запросов функций.

Большинство пользователей doxygen используют его для кода C и С++, поэтому, естественно, эти языки имеют самую зрелую поддержку, а результат больше настроен на функции и потребности для этих языков. Тем не менее, также пожелания и проблемы с другими языками воспринимаются всерьез.

Обратите внимание, что я делаю почти все разработки doxygen и большинство тестов на Mac.

Ответ 2

Я автор appledoc, так что этот ответ может быть предвзятым:) Я пробовал все упомянутые генераторы, хотя (и больше), но разочарован, так как ни один из них не дал результаты, которые я хотел иметь (аналогичные цели, как вы).

В соответствии с вашими точками (я упоминаю только appledoc и doxygen, я не очень хорошо помню headerdoc):

Согласованный вид: appledoc из коробки, другой нужно настроить css, но, вероятно, выполнимо.
Генерация наборов документации (для ссылок на Xcode): полная поддержка полностью доступной для поиска и документации с возможностью выбора, doxygen генерирует xml и makefile, которые вы должны вызывать самостоятельно. Кроме того, appledoc поддерживает опубликованные docset из коробки.
Категории: appledoc позволяет объединять категории с известными классами или оставлять их отдельными, базовые и другие категории класса Apple перечислены отдельно в индексный файл. doxygen: это не сработало, когда я попробовал.
Пользовательские справочные страницы: appledoc поддерживает из коробки, используя либо уценку, либо пользовательский html, doxygen: вы можете включить пользовательскую документацию в на главной странице, не знаю, можете ли вы добавить больше страниц.
Простая командная строка: зависит от того, как вы на это смотрите: appledoc может принимать все аргументы с помощью переключателей командной строки (но также поддерживает дополнительные файлы plist для глобальных и проектов), поэтому его очень легко интегрировать со сценариями сборки. doxygen требует использования конфигурационного файла для настройки всех параметров.
Большие кодовые базы: все инструменты должны поддерживать это, хотя время не сравнивалось. Также не уверен, что какой-либо инструмент поддерживает кешированные значения (выполняется над ранее собранными данными, чтобы сэкономить некоторое время). Я изучаю добавление этого для следующей основной версии.

Это некоторое время с тех пор, как я попытался использовать другие инструменты, поэтому вышеупомянутые проблемы с doxygen/headerdoc, возможно, были рассмотрены! Сам appledoc также имеет недостатки: как вы упоминаете, нет поддержки перечислений, структур, функций и т.д. (была проделана некоторая работа в этом направлении, проверить эту вилку), и у него есть собственный набор проблем, который может помешать вам использовать его, в зависимости от ваших требований.

В настоящее время я работаю над основным обновлением, которое охватывает наиболее вопиющие проблемы, включая поддержку перечислений, структур и т.д. Я регулярно выдвигаю новые материал для экспериментальной ветки, как только я закончу большие куски и сделаю его достаточно стабильным, чтобы вы могли следить за прогрессом. Но это все еще очень рано, и прогресс зависит от моего времени, так что это может занять некоторое время до рабочего решения.

Ответ 3

Теперь Xcode 5 проанализирует ваши комментарии, чтобы найти документацию и отобразить ее:

Вам больше не нужно использовать appledoc или doxygen (по крайней мере, когда вы не хотите экспортировать свои документы). Более подробную информацию можно найти здесь