Генератори документації Objective-C: HeaderDoc проти Doxygen проти AppleDoc

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

Ось те, що я зміг зрозуміти з мого початкового проходу:

Плюси HeaderDoc: узгоджується з існуючими документами apple, сумісність із створенням яблучних докторів
HeaderDoc мінуси: важко змінити поведінку, над проектом активно не працюють, багато хто від нього відмовився (це означає, що має бути щось дефіцитне, хоча я не можу визначити це кількісно ).

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

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

Це звучить точно? Наше бажане рішення матиме:

• Послідовний вигляд та відчуття яблук об’єктив-с посилання на клас
• Можливість клацання опцією витягувати посилання на документацію з Xcode, а потім посилатись на документ (так само, як класи Apple)
• Розумна обробка категорій, розширень тощо (навіть власні категорії класів Apple)
• Можливість створювати наші власні довідкові сторінки (наприклад, ця сторінка: Завантаження…, яка може включати зображення та легко зв’язуватись із згенерованими посиланнями на класи, наприклад, як посилання на клас UIViewController від Apple посилається на пов’язану сторінку.
• Легко запускати команди командного рядка, які можна інтегрувати в сценарії побудови
• Витончена обробка дуже великої кодової бази

Виходячи з усієї наведеної вище інформації, чи є одне з наведених вище рішень явно кращим за інші? Будемо вдячні за будь-які пропозиції чи інформацію, яку слід додати.

Як творець і провідний розробник доксигену, дозвольте мені також висловити свою точку зору
(очевидно також упереджене ;-)

Якщо ви шукаєте 100% вірну копію власного стилю документації Apple, то AppleDoc - кращий вибір у цьому відношенні. З доксигеном вам буде важко отримати такий самий вигляд, тому я б не рекомендував спробувати.

Що стосується наборів Xcode; Apple надає інструкції, як налаштувати це за допомогою доксигену (написано під час випуску Xcode 3). Для Xcode 4 також є гарний посібник, як інтегрувати кисень.

Починаючи з версії 1.8.0, doxygen підтримує розмітку Markdown , а також велику кількість додаткових команд розмітки .

За допомогою doxygen ви можете включити документацію на головну сторінку (@mainpage), а також на підсторінки (за допомогою @subpage або @page). Усередині сторінки ви можете створювати розділи та підрозділи. Насправді, керівництво користувача доксигену було повністю написане з використанням доксигену. Крім того, ви можете групувати класи або функції разом (за допомогою @defgroup та @ingroup), а всередині класу створювати власні розділи (за допомогою @name).

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

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

Кисень також виходить за рамки чистої документації; doxygen може створювати різні графіки та діаграми з вихідного коду (див. параметри, пов’язані з крапками ). Doxygen також може створити версію коду, яку можна переглядати та виділити синтаксисом, а також перехресне посилання на цю документацію (див. Параметри, пов’язані з вихідним браузером ).

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

Хороший приклад із реального життя використання кисню для Objective-C можна знайти тут .

Розвиток кисню сильно залежить від відгуків користувачів. У нас є активний список розсилки для запитань та обговорень, а також відстежувач помилок як для помилок, так і для запитів на функції.

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

Зверніть увагу, що я майже всі розробляю кисень та більшість тестувань на Mac.

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

Відповідно до Ваших зауважень (я згадую лише appledoc та doxygen, я не дуже добре пам’ятаю headerdoc):

1. Послідовний вигляд: appledoc готовий, інші потрібно налаштувати css, але, можливо, це можливо.

2. Генерування наборів документації (для посилань на Xcode): повна підтримка appledoc документації, яку можна шукати та з можливістю натискання опцій, doxygen генерує xml та makefile, які потрібно викликати самостійно. Крім того, appledoc підтримує опубліковані набори документів з коробки.

3. Категорії: appledoc дозволяє об’єднати категорії з відомими класами або залишити їх окремими, основи та інші категорії класів apple перераховані окремо у файлі індексу . doxygen: це не спрацьовувало найкраще, коли я спробував.

4. Користувальницькі довідкові сторінки: appledoc підтримує нестандартно, використовуючи розмітку або спеціальний html, doxygen: ви можете включити спеціальну документацію на головну сторінку, не знаєте, чи можете ви включити більше сторінок.

5. Простий командний рядок: залежить від того, як ви на це дивитесь: appledoc може приймати всі аргументи за допомогою перемикачів командного рядка (але також підтримує необов’язкові глобальні файли та файли plist налаштувань проекту), тому інтегрувати його зі сценаріями побудови має бути дуже просто. doxygen вимагає використання файлу конфігурації для налаштування всіх параметрів.

6. Великі бази кодів: усі інструменти повинні це підтримувати, хоча не порівнювали за часом. Також не впевнений, що будь-який інструмент підтримує кешовані значення (запуск раніше зібраних даних, щоб заощадити час) - я хочу додати це для наступного основного випуску.

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

Зараз я працюю над основним оновленням, яке охоплюватиме найяскравіші проблеми , включаючи підтримку переліків, структур тощо. Я регулярно надсилаю нові матеріали до експериментальної гілки, як тільки закінчую більші фрагменти і роблю їх досить стабільними, щоб ви могли стежити за прогрес. Але все ще дуже рано, і прогрес залежить від мого часу, тому може знадобитися досить багато часу, поки не запрацює рішення.

Тепер Xcode 5 проаналізує ваші коментарі для пошуку документації та її відображення:

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