Я разработчик Mac с очень сильным фоном Java. Я документировал свои источники, используя Javadoc, много.
Doxygen работает с Objective-C (и, следовательно, с кодом Cocoa), Apple также предоставляет headerdoc инструмент для создания документации. Затем есть GNUstep autogsdoc.
Существует проект с открытым исходным кодом Appledoc, который может генерировать документацию, как официальные документы Apple.
https://github.com/tomaz/appledoc
Для Swift существует еще одно приложение с открытым исходным кодом, называемое jazzy.
Xcode 5 обновил оперативную справку: Теперь вы можете документировать свой код в своих комментариях, например, с помощью javadoc. Когда вы нажимаете документированный объект/метод, нажимая option ⌥, вам будут представлены ваши комментарии в приятном всплывающем окне, например, документация от Apple:
Если вы используете Xcode ≥ 3.0, вы, вероятно, захотите проверить Doxygen, как предложили другие, а затем прочитать эту статью Сайт разработчика Apple для создания наборов документации Xcode для вашего проекта (можно просмотреть в справочной системе Xcode) с помощью Doxygen.
Я чувствую, что ни один из них не достаточно хорош, и созданные ими документы не соответствуют стандарту Apple. Таким образом, я сообщил об ошибке Apple в запросе собственного инструмента для создания документации в Xcode, пожалуйста, проголосовать за него, если вы также хотите, чтобы такой инструмент.
Я использую Doxygen и Doxyclean для создания более чистой, более подобной Apple документации, которую производит Doxygen.
(Следует сказать, что Doxyclean не переформатирует весь вывод Doxygen - вы определенно получаете подмножество документации, которую вы получите прямо от Doxygen).
Я знаю, что это старый вопрос, но я нашел этот недавний плагин Xcode невероятно полезным:
https://github.com/onevcat/VVDocumenter-Xcode
Просто введите /// перед методом, и он автоматически сгенерирует документацию, поэтому дается, например:
- (id)fooBar:(NSString *)woo;
После ввода /// до метода, который он произведет:
/**
* <#Description#>
*
* @param woo <#woo description#>
*
* @return <#return value description#>
*/
У меня подобный фон на Java, и у меня был тот же вопрос, когда я узнал Objective-C и Cocoa. В настоящее время нет инструмента, идеально подходящего для Objective-C, но Doxygen - лучший вариант на данный момент. (Я согласен с тем, что HeaderDoc слишком сложный, особенно для небольших проектов, и каждый другой инструмент, который я нашел, является мертвым или отказоустойчивым, включая AutoDoc и ObjcDoc.) Разработчик Doxygen улучшил поддержку Obj-C последовательно в течение последних нескольких выпусков, в том числе несколько ошибок, которые я отправил, когда протоколы обрабатывались неправильно.
Внутри Xcode я создаю цель Documentation с одной фазой Run Script, которая вызывает Doxygen с использованием doxyfile, сохраненного в каталоге проекта. Это помогает создать символическую ссылку на исполняемый файл Doxygen в /usr/local/bin, чтобы у вас не были машинные пути в общем файле doxyfile.
Doxygen поддерживает практически все теги комментариев, которые вы ожидаете увидеть в Javadoc, плюс многое другое. Я широко использовал его в разработке с открытым исходным кодом, которую я разрабатываю - результирующая документация автоматически генерируется с использованием крюка post-commit Subversion и доступна в Интернете:
http://dysart.cs.byu.edu/CHDataStructures/
Обратите внимание на диаграммы, которые наследуют документ и сотрудничают. Они могут быть сгенерированы с помощью инструмента точка, доступного с помощью GraphViz, v1.13 или v2.20. Диаграммы представляют собой интерактивные карты изображений HTML, которые помогают компенсировать недостаток информации в верхней части, которую вы ожидаете в Javadoc (например, иерархия наследования) или документация Apple Cocoa (например, принятые протоколы).
В стороне, поскольку CHDataStructures - это структура с большим количеством публичных API, я пишу лоты комментариев - примерно 70% моих заголовочных файлов. Поскольку документация более полезна в форме, созданной Doxygen, я предпочитаю исключать большинство комментариев из версии Release заголовков, что значительно снижает размер на диске для заголовков. Я опубликовал полное объяснение и код на BYU CocoaHeads wiki:
http://cocoaheads.byu.edu/wiki/stripping-comments-source-code
Забудьте headerdoc. Headerdoc - это куча /** poo */. Придерживайтесь doxygen. Он отлично работает и создает хорошую документацию. Он может понять (или, по крайней мере, не взорвать) более уникальные конструкции Objc (протоколы, категории и т.д.). Doc-разметка Doxygen - это действительно суперсет (с правильной конфигурацией) headerdoc.
Я рекомендую HeaderDoc, как указано в WWDC 2103 Видео 401 - Основные концепции Xcode, раздел Интегрированный документ. Он полностью поддерживается в Xcode 5
PS: Там отличный учебник о том, как использовать HeaderDoc на raywenderlich.com
Swift 2.0 + Xcode 7.0 beta 4
Обозначение было изменено (:param: больше не работает...)
/// Creates the string representation of the poo with requested size.
///
/// - warning: Be carefull! Poos can hurt.
/// - parameter size: requested size of the poo
/// - returns: string representation of the poo
func makePoo(size: String) -> String
{
return "Ouch. This is \(size) poo!"
}
И это выглядит так:
Вы можете использовать либо ///, либо /** */
Еще одна вещь, которую следует помнить о Doxygen, - это то, что она отлично справляется с С++, и поэтому, если ваша кодовая база Objective-C включает в себя общий движок С++, будет иметь и ту же базу документации.
Вот полное и легкое руководство по документации xcode:
Документирование вашего кода с комментариями в Xcode 5
В нем также указывается, как включить обнаружение предупреждений в вашем коде документации.
Я не знаю ни одного поддерживаемого Xcode инструментами doc, и я не помню, чтобы увидеть какую-либо разметку документации в любом образце кода Apple.
Лично я использую Doxygen, который очень подходит для моих потребностей.