appledoc

О AppleDoc

ВАЖНОЕ ПРИМЕЧАНИЕ: требуются сотрудники

appledoc — это инструмент командной строки, который помогает разработчикам Objective-C создавать документацию по исходному коду в стиле Apple из специально отформатированных комментариев к исходному коду. Он предназначен для ввода как можно более читаемых комментариев исходного кода и использования комментариев, а также окружающего исходного кода для создания визуально привлекательной документации в форме HTML, а также полностью индексируемого и доступного для просмотра набора документации Xcode. Хотя существует несколько инструментов, позволяющих создавать HTML-документацию для Objective-C, все известные мне не соответствуют минимуму целей, описанных ниже.

Основные цели appledoc:

• Читаемые человеком комментарии к исходному коду.
• Простые перекрестные ссылки на объекты и члены.
• Создавайте HTML-документацию по исходному коду в стиле Apple.
• Создайте и установите полностью индексированный и доступный для просмотра набор документации Xcode.
• Единый инструмент для управления генерацией от анализа исходного кода до установки комплекта документации.
• Легко настраиваемый вывод.
• 100% реализация Objective-C для легкой отладки.

Чтобы сделать вашу работу с appledoc максимально комфортной, мы настоятельно рекомендуем прочитать этот документ целиком, а также всю онлайн-документацию, упомянутую в разделе «использование appledoc» ниже!

Использование appledoc разрешено на условиях, перечисленных в разделе «ЛИЦЕНЗИЯ» внизу этого файла!

Хотите быть в курсе? Следуйте за нами в Твиттере - @gentlebytes.

Быстрая установка

Рекомендуемый способ — клонировать проект GitHub и скомпилировать инструмент из Xcode. Поскольку клонирование проекта GitHub создаст ссылку на основной репозиторий, это также значительно упрощает будущее обновление. Для установки введите в Терминале следующее:

 git clone git://github.com/tomaz/appledoc.git

Это создаст каталог appledoc. Внутри вы можете найти рабочее пространство Xcode appledoc.xcworkspace; откройте его и скомпилируйте цель appledoc — это должно работать «из коробки», однако ваша система должна соответствовать минимальным системным требованиям, см. ниже. Я рекомендую вам скопировать полученный исполняемый файл appledoc из каталога сборки в один из каталогов вашего пути ( echo $PATH ), чтобы сделать его легко доступным.

Необязательно: Appledoc является автономным и содержит необходимые файлы шаблонов. ЕСЛИ вы хотите изменить эти значения по умолчанию из подкаталога «Шаблоны» в одно из ожидаемых мест:

• ~/Библиотека/Поддержка приложений/appledoc
• ~/.appledoc

Вы также можете использовать скрипт install-appledoc.sh для выполнения быстрой установки. Откройте терминал и перейдите в каталог appledoc. Введите следующую команду:

 sudo sh install-appledoc.sh (if you need templates add '-t default')

По умолчанию он компилирует appledoc и устанавливает его двоичный файл в /usr/local/bin, а шаблоны (если необходимо) в ~/.appledoc. Вы можете переопределить эти каталоги с помощью опций -b и -t соответственно. Например:

 sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application Support/appledoc

Альтернативно с Homebrew:

 brew install appledoc

Homebrew не устанавливает шаблоны по умолчанию.

Использование AppleDoc

Используйте appledoc --help , чтобы просмотреть список всех ключей командной строки. Подробную информацию о appledoc можно найти на сайте appledoc. Также прочитайте вики-страницы, чтобы найти более подробные статьи.

Используйте группу Appledoc Google в качестве форума для вопросов по использованию или других общих вопросов.

Используйте страницу проблем Appledoc, чтобы отправлять запросы об ошибках и функциях. Прежде чем отправлять новые проблемы, проверьте форумы, чтобы узнать, есть ли там ответ на ваш вопрос. Если вы не можете подтвердить свою проблему как запрос на новую функцию или ошибку, вам следует начать с форума, чтобы поддерживать чистоту проблем GitHub. Также прочитайте задачи, чтобы узнать, существует ли она уже, и проголосуйте за нее или добавьте комментарий (не забывайте о закрытых проблемах).

Советы по установке

Чтобы быть в курсе событий, просто зайдите в Терминал и перейдите в каталог appledoc, выполните git pull и перекомпилируйте appledoc.xcodeproj. Не забудьте перезаписать исполняемый файл appledoc, который вы скопировали в $PATH :)

Если вы также хотите скомпилировать и запустить цель AppledocTests (модульные тесты), вам необходимо скопировать все платформы, указанные в группе «Библиотеки и платформы», в каталог общих платформ, прежде чем создавать цель модульных тестов! Это не требуется для создания самого инструмента appledoc.

Интеграция с Xcode

Вы можете настроить Xcode для автоматизации создания документов AppleDoc. Узнайте, как использовать сценарий запуска и этапы сборки вашего проекта.

Советы по использованию набора документов

Предварительно созданная документация и наборы документов для большинства платформ Cocoa доступны по адресу:

• КакаоДокументация

Если у вас есть набор документов, вы можете использовать его с браузером документации:

• Xcode
• Бросаться

Поиск неисправностей

Есть проблемы? Вот что вы можете сделать для устранения неполадок:

1. Убедитесь, что у вас установлена ​​последняя версия appledoc. Попробуйте git pull и снова запустите последнюю версию.
2. ЕСЛИ у вас установлены файлы шаблонов, убедитесь, что вы используете последнюю версию — удалите предопределенные папки и попросите appledoc снова скопировать файлы из встроенного архива (см. раздел «Быстрая установка» выше).
3. Увеличьте уровень детализации с помощью переключателя командной строки --verbose . Уровень по умолчанию — 2, но вы можете постепенно увеличивать уровень детализации до 6, при этом каждый уровень будет предоставлять вам более подробную информацию. Поскольку это даст вам гораздо больше информации, вы можете сосредоточиться только на конкретном наборе исходных файлов, с которыми у вас возникли проблемы. Обратите внимание, что увеличение детализации приведет к снижению производительности, поэтому использование уровней выше 4 для повседневного использования не рекомендуется.
4. Appledoc — проект с открытым исходным кодом! У вас есть весь исходный код, поэтому запустите его из Xcode. Вы можете настроить Xcode для передачи нужных аргументов командной строки и добавить точки останова, которые помогут вам изолировать проблему. Если вы чувствуете, что хотите внести больший вклад в сообщество, вы можете создать форк проекта на GitHub и добавить в него функции. Держите нас в курсе, чтобы мы могли добавить эти функции и в основной репозиторий — если возможно, включите модульные тесты.
5. Если вы считаете, что нашли ошибку или хотите запросить новую функцию, перейдите на страницу проблем Appledoc. Сначала прочитайте существующие проблемы, чтобы узнать, есть ли там уже запрос (если вы используете главную ветку, также прочитайте закрытые проблемы, поскольку ваш запрос, возможно, уже рассмотрен, но еще не объединен с основной веткой). Вы можете проголосовать за существующие запросы, чтобы помочь нам решить, на каких функциях следует сосредоточиться, или вы можете добавить комментарий, чтобы помочь в решении этой проблемы. Если вы не нашли там запроса, создайте новую задачу; по возможности включите части исходных файлов, которые вызывают у вас проблемы, и/или описание или шаги, которые к ним приводят.
6. Если у вас возникли проблемы с некоторыми исходными файлами и вы не хотите публиковать их в Интернете, вы можете связаться с нами по электронной почте, указанной ниже. Мы сделаем все возможное, чтобы помочь вам, но имейте в виду, что appledoc не является коммерческим продуктом; он создается и поддерживается в наше свободное время, поэтому ресурсы ограничены.

Примечания разработчика

Если вы хотите внести свой вклад, см. файл «Заметки разработчика» для краткого обзора того, как appledoc работает внутри.

Минимальные системные требования

• Xcode 4.5 или выше для компиляции
• OS X 10.7 для компиляции и запуска

Лицензия

appledoc имеет модифицированную лицензию BSD. Говоря простым языком: вам разрешено делать с кодом все, что вы пожелаете, изменять, распространять, встраивать в свои продукты (бесплатные или коммерческие), но вы должны указать авторские права, условия использования и отказ от ответственности, как указано в лицензии, то же самое. так же, как и любой другой лицензионный код BSD. Вы, конечно, можете использовать документацию, созданную appledoc, для ваших продуктов (бесплатную или коммерческую), но вы должны указать appledoc либо в самой документации, либо в другом подходящем месте, например на вашем веб-сайте.

Если по какой-либо причине вы не можете согласиться с этими условиями, свяжитесь с нами через контактную форму на странице «О нас», мы сделаем все возможное, чтобы помочь вам и найти работоспособное решение!

Copyright (c) 2009–2011, Gentle Bytes. Все права защищены.

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

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

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

• Распространение документации, созданной appledoc, должно включать указание Appledoc либо в самой документации, либо на других соответствующих носителях.

• Ни название appledoc, Gentle Bytes, ни имена его участников не могут использоваться для поддержки или продвижения продуктов, созданных на основе этого программного обеспечения, без специального предварительного письменного разрешения.

ЭТО ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ ОБЛАДАТЕЛЯМИ АВТОРСКИХ ПРАВ И УЧАСТНИКАМИ «КАК ЕСТЬ», И ЛЮБЫЕ ЯВНЫЕ ИЛИ ПОДРАЗУМЕВАЕМЫЕ ГАРАНТИИ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ, ПОДРАЗУМЕВАЕМЫМИ ГАРАНТИЯМИ ТОВАРНОЙ ЦЕННОСТИ И ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ. НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ ОБЛАДАТЕЛЬ АВТОРСКИХ ПРАВ ИЛИ УЧАСТНИКИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ ПРЯМЫЕ, КОСВЕННЫЕ, СЛУЧАЙНЫЕ, СПЕЦИАЛЬНЫЕ, ПРИМЕРНЫЕ ИЛИ КОСВЕННЫЕ УБЫТКИ (ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ, ПРИОБРЕТЕНИЕ ЗАМЕНЯЮЩИХ ТОВАРОВ ИЛИ УСЛУГ; ПОТЕРЮ ИСПОЛЬЗОВАНИЯ, ДАННЫХ, ИЛИ ПРИБЫЛЬ ИЛИ ПЕРЕРЫВ БИЗНЕСА), КАКОЙ-ЛИБО ВЫЗВАННОЙ И НА ЛЮБОЙ ТЕОРИИ ОТВЕТСТВЕННОСТИ, КАК ДОГОВОР, СТРОГО ОТВЕТСТВЕННОСТЬ ИЛИ ПРАВИЛЬНОЕ ПРАВОНАРУШЕНИЕ (ВКЛЮЧАЯ НЕБРЕЖНОСТЬ ИЛИ ДРУГОЕ), ВОЗНИКАЮЩЕЕ ЛЮБЫМ СПОСОБОМ ИСПОЛЬЗОВАНИЯ ЭТОГО ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ, ДАЖЕ ЕСЛИ УВЕДОМЛЕНО ОБ ЭТОМ ПРОГРАММНОМ ОБЕСПЕЧЕНИИ. ВОЗМОЖНОСТЬ ТАКОГО ПОВРЕЖДЕНИЯ.

Джентл Байтс [email protected]