Цель-с генераторами документации: HeaderDoc и помощи Doxygen и AppleDoc
Мне нужно реализовать решение для создания документации для моего рабочего места и сузить его до трех, упомянутых в названии. Я смог найти очень мало информации на пути формализованных сравнений между этими решениями, и я надеюсь, что те из вас, кто имеет опыт в одном или нескольких из вышеперечисленных, могут взвесить:
вот что я смог почерпнуть из моего первоначального прохода:
HeaderDoc плюсы: в соответствии с существующими apple документы, совместимость с созданием apple docsets
Headerdoc минусы: трудно изменить поведение, проект не активно работал, многие переключились от него (что означает, что должно быть что-то недостаточное, хотя я не могу его количественно оценить).
Doxygen Pros:
Активная поддержка сообщества b / c широкого использования базы, очень настраиваемый, большинство типов вывода (например, latex и т. д.)
Минусы Помощи Doxygen :
Требуется работа, чтобы он выглядел / вел себя в соответствии с документами Apple, совместимость с наборами документов apple не является как просто
AppleDoc Pros:
Выглядит в соответствии с существующими документами apple, совместимость с созданием наборов документов apple,
Минусы AppleDoc :
Проблема с документацией типов, перечислений и функций, активно разрабатываемых
Это звучит точно? Наше желаемое решение будет иметь:
- последовательный внешний вид с яблоками objective-C Class reference
- возможность выбора-нажмите, чтобы вытащить ссылку на документацию изнутри Xcode, а затем ссылка на doc (так же, как классы apple)
- умная обработка категорий, расширений и тому подобное (даже пользовательские категории классов apple)
- возможность создавать свои собственные справочные страницы (например, эта страница: загрузка... которая может включать изображения и легко связываться с созданными ссылками на классы, например, как ссылки класса UIViewController от apple на связанную страницу.
- легко запускать команды командной строки, которые могут быть интегрированы в скрипты сборки
- изящная обработка очень большой кодовой базы
исходя из приведенной выше информации, какие-то из вышеперечисленных решений явно лучше, чем другие? Любые предложения или информация для добавления будут чрезвычайно признательны.
3 ответа:
как создатель и ведущий разработчик doxygen, позвольте мне также представить свою точку зрения
(очевидно, предвзято, а также; -)Если вы ищете 100% верную копию собственного стиля документации Apple, то AppleDoc является лучшим выбором в этом отношении. С doxygen вам будет трудно получить тот же самый взгляд, поэтому я бы не рекомендовал пытаться.
в отношении наборов документов 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 часто задаваемые вопросы пример)Doxygen не ограничивается Objective-C, он поддерживает широкий спектр языков, включая C, C++ и Java. Doxygen также не ограничивается платформой Mac, например, он работает на Windows и Linux тоже. Вывод Doxygen также поддерживает больше, чем просто HTML; вы можете создавать PDF-вывод (через LaTeX) или RTF и man-страницы.
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 поддерживает опубликовано docsets из коробки.
категории: appledoc позволяет слияние категорий для известных классов или оставить их отдельно, фонд и другие категории класса apple перечислены отдельно в индекс. доксиген: это не сработало лучше, когда я попробовал.
пользовательские справочные страницы: appledoc поддерживает из коробки, используя либо markdown или пользовательский html, doxygen: вы можете включить пользовательскую документацию на главную страницу, не знаю, можете ли вы включить больше страниц.
простая командная строка: зависит от того, как вы на нее смотрите: appledoc может принимать все аргументы через параметры командной строки (но также поддерживает необязательные глобальные и проектные настройки plist-файлов), поэтому его должно быть очень легко интегрировать со скриптами сборки. doxygen требует использования конфигурационного файла для настройки всех параметров.
большие кодовые базы: все инструменты должны поддерживать это, хотя и не сравнивались по времени. Также не уверен, что какой - либо инструмент поддерживает кэшированные значения (запуск ранее собранных данных для экономии времени) - я изучаю добавление этого для следующего основного выпуска.
Это некоторое время с тех пор, как я попытался использовать другие инструменты, так что вышеупомянутые проблемы с doxygen/headerdoc, возможно, были решены! сам appledoc также имеет недостатки: как вы упомянули, нет поддержки перечислений, структур, функций и т. д. (В этом направлении была проделана некоторая работа,проверить эту вилку), и у него есть свой набор вопросов что может помешать вам использовать его, в зависимости от ваших требований.
в настоящее время я работаю над основным обновлением, которое будет охватить большинство вопиющих вопросов, включая поддержку перечислений, структур и т. д. Я регулярно подталкиваю новый материал к экспериментальной ветке, Как только я заканчиваю большие куски и делаю его достаточно стабильным, чтобы вы могли следить за прогрессом. Но это все еще очень рано, и прогресс зависит от моего времени, поэтому может потребоваться довольно много времени до рабочего решения.
Xcode 5 теперь будет анализировать Ваши комментарии для поиска документации и отображения ее:
вам больше не нужно использовать appledoc или doxygen (по крайней мере, когда вы не хотите экспортировать свои документы). Более подробную информацию можно найти здесь
