Генераторы документации Objective-C: HeaderDoc против Doxygen против AppleDoc
Мне нужно реализовать решение для создания документации для моего рабочего места и сузить его до трех, упомянутых в названии. Мне удалось найти очень мало информации о формализованных сравнениях между этими решениями, и я надеюсь, что те из вас, кто имеет опыт в одном или нескольких из вышеперечисленных, могут взвесить:
Вот что я смог почерпнуть из моего начального паса:
Плюсы HeaderDoc: в соответствии с существующими документами Apple, совместимость с созданием документов Apple
Недостатки HeaderDoc: Трудно изменить поведение, над проектом не ведется активная работа, многие от него отказались (имеется в виду, что должно быть что-то недостаточно, хотя я не могу дать количественную оценку).
Doxygen Pros: сообщество активной поддержки b/c с широкой базой использования, очень настраиваемый, большинство типов вывода (например, латекс и т. Д.)
Минусы Doxygen: Принимает меры, чтобы он выглядел / вел себя в соответствии с документами Apple, совместимость с документами Apple не так проста
AppleDoc Pros: выглядит в соответствии с существующими документами Apple, совместимость с созданием документов Apple,
AppleDoc Минусы: проблема с документацией typedefs, перечислений и функций, активно разрабатывается
Это звучит точно? Наше желаемое решение будет иметь:
- Последовательный внешний вид с яблоком
- Возможность щелчка по опции, чтобы получить ссылку на документацию из XCode, а затем ссылку на документ (точно так же, как классы Apple)
- Умная обработка категорий, расширений и тому подобного (даже пользовательских категорий классов Apple)
- Возможность создавать собственные справочные страницы (например, эту страницу: Загрузка…, которая может включать в себя изображения и быть легко связываемой из сгенерированных ссылок на классы, например, как ссылка на класс UIViewController от Apple ссылается на связанную страницу.
- Простые команды командной строки, которые можно интегрировать в сценарии сборки
- Изящная обработка очень большой кодовой базы
Основываясь на всей приведенной выше информации, являются ли какие-либо из вышеуказанных решений явно лучше, чем другие? Любые предложения или информацию, чтобы добавить, будет очень признателен.
3 ответа
Как создатель и ведущий разработчик doxygen, позвольте мне также высказать свою точку зрения
(очевидно, также предвзято;-)
Если вы ищете 100% точную копию собственного стиля документации Apple, то AppleDoc - лучший выбор в этом отношении. С доксигеном вам будет трудно получить такой же внешний вид, поэтому я бы не рекомендовал пробовать.
Что касается документов Xcode; Apple предоставляет инструкции, как настроить это с помощью doxygen (написано во время выхода Xcode 3). Для Xcode 4 есть также хорошее руководство по интеграции doxygen.
Начиная с версии 1.8.0, doxygen поддерживает разметку Markdown, а также большое количество дополнительных команд разметки.
С doxygen вы можете включить документацию на главной странице (@mainpage), а также на подстраницах (используя @subpage или @page). Внутри страницы вы можете создавать разделы и подразделы. На самом деле, руководство пользователя doxygen было полностью написано с использованием doxygen. Кроме того, вы можете группировать классы или функции вместе (используя @defgroup и @ingroup) и внутри класса создавать пользовательские разделы (используя @name).
Doxygen использует файл конфигурации в качестве входных данных. Вы можете создать шаблон со значениями по умолчанию, используя doxygen -g или используйте графический редактор для его создания и редактирования. Вы также можете передать параметры через doxygen через скрипт, используя doxygen - (см. вопрос 17 в FAQ для примера)
Doxygen не ограничивается Objective-C, он поддерживает широкий спектр языков, включая C, C++ и Java. Doxygen также не ограничивается платформой Mac, например, работает на Windows и Linux. Вывод Doxygen также поддерживает не только HTML; Вы можете генерировать вывод PDF (через LaTeX) или RTF и справочные страницы.
Doxygen также выходит за рамки чистой документации; doxygen может создавать различные графики и диаграммы из исходного кода (см. опции, связанные с точками). Doxygen также может создать версию вашего кода с подсветкой и синтаксисом и сопоставить ее с документацией (см. Опции, связанные с исходным браузером).
Doxygen очень быстр для небольших и средних проектов (хотя генерация диаграмм может быть медленной, но в настоящее время она работает на нескольких ядрах процессора параллельно, а графики из одного прогона повторно используются в следующем прогоне). Для очень больших проектов (например, миллионов строк кода) doxygen позволяет разбивать проекты на несколько частей, а затем связывать их вместе, как я объяснил здесь.
Хороший реальный пример использования doxygen для Objective-C можно найти здесь.
Развитие doxygen сильно зависит от отзывов пользователей. У нас есть активный список рассылки для вопросов и обсуждений, а также система отслеживания ошибок и запросов.
Большинство пользователей doxygen используют его для кода на C и C++, поэтому, естественно, эти языки имеют наиболее развитую поддержку, а вывод более приспособлен к функциям и потребностям этих языков. Тем не менее, пожелания и проблемы с другими языками воспринимаются серьезно.
Обратите внимание, что я сам почти все занимаюсь разработкой и тестированием doxygen на Mac.
Я являюсь автором appledoc, поэтому этот ответ может быть предвзятым:) Я попробовал все упомянутые генераторы, хотя (и больше), но был разочарован, так как ни один из них не дал результатов, которые я хотел получить (аналогичные цели, как вы).
В соответствии с вашими замечаниями (я упоминаю только appledoc и doxygen, я не очень хорошо помню headerdoc):
Последовательный вид: appledoc из коробки, другие должны настроить CSS, но, вероятно, выполнимо.
Генерация наборов документации (для ссылок XCode): полная поддержка appledoc для документов с возможностью поиска и выбора, доступных из коробки, doxygen генерирует xml и makefile, которые вам нужно вызвать самостоятельно. Кроме того, appledoc поддерживает опубликованные наборы документов из коробки.
Категории: appledoc позволяет объединять категории с известными классами или оставлять их отдельно, фундаментальные и другие категории классов Apple перечислены отдельно в индексном файле. Doxygen: это не сработало лучше, когда я попробовал.
Пользовательские справочные страницы: appledoc поддерживает " из коробки", используя уценку или пользовательский html, doxygen: вы можете добавить пользовательскую документацию на главную страницу, не знаю, можете ли вы добавить больше страниц.
Простая командная строка: зависит от того, как вы на это смотрите: appledoc может принимать все аргументы через переключатели командной строки (но также поддерживает необязательные глобальные и файлы параметров проекта), поэтому его должно быть очень легко интегрировать со скриптами сборки. Doxygen требует использования файла конфигурации для настройки всех параметров.
Большие базы кода: все инструменты должны поддерживать это, хотя и не сравнивать по времени. Также не уверен, что какой-либо инструмент поддерживает кэшированные значения (работает с ранее собранными данными, чтобы сэкономить время) - я смотрю на добавление этого для следующего основного выпуска.
Прошло некоторое время с тех пор, как я пытался использовать другие инструменты, поэтому вышеупомянутые проблемы с doxygen / headerdoc могли быть решены! У самого appledoc также есть недостатки: как вы упомянули, здесь нет поддержки перечислений, структур, функций и т. д. (в этом направлении была проделана некоторая работа, проверьте эту ветвь), и у него есть свой собственный набор проблем, которые могут помешать вам его использовать, в зависимости от ваши требования.
В настоящее время я работаю над серьезным обновлением, которое будет охватывать большинство явных проблем, включая поддержку перечислений, структур и т. Д. Я регулярно добавляю новые вещи в экспериментальную ветку, как только заканчиваю большие куски и делаю их достаточно стабильными, чтобы вы могли следить за прогресс. Но это все еще очень рано, и прогресс зависит от моего времени, поэтому может потребоваться довольно много времени, пока не будет найдено решение.
Xcode 5 теперь будет анализировать ваши комментарии для поиска документации и отображать ее:
Вам больше не нужно использовать appledoc или doxygen (по крайней мере, когда вы не хотите экспортировать свои документы). Более подробную информацию можно найти здесь